From 3f41adff750f671b6c46da14be3017b75a7f546c Mon Sep 17 00:00:00 2001
From: Mai Development <mai@local>
Date: Mon, 26 Jan 2026 23:21:40 -0500
Subject: [PATCH] docs: establish fresh planning foundation with new features

- Update PROJECT.md: Add Android, visualizer, and avatar to v1
- Update REQUIREMENTS.md: 99 requirements across 15 phases (fresh slate)
- Add comprehensive README.md with setup, architecture, and usage
- Add PROGRESS.md for Discord forum sharing
- Add .gitignore for Python/.venv and project artifacts
- Note: All development via Claude Code/OpenCode workflow
- Note: Python deps managed via .venv virtual environment

Core value: Mai is a real collaborator, not a tool. She learns from you,
improves herself, has boundaries and opinions, and becomes more *her* over time.

v1 includes: Model interface, Safety, Resources, Memory, Conversation,
CLI, Self-Improvement, Approval, Personality, Discord, Offline, Voice
Visualization, Avatar, Android App, Device Sync.
---
 .gitignore                |  64 +++++--
 .planning/PROGRESS.md     | 187 ++++++++++++++++++
 .planning/PROJECT.md      |  39 +++-
 .planning/REQUIREMENTS.md |  58 +++++-
 README.md                 | 393 ++++++++++++++++++++++++++++++++++++++
 5 files changed, 715 insertions(+), 26 deletions(-)
 create mode 100644 .planning/PROGRESS.md
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index 2d7396f..86ae503 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,18 +1,60 @@
 # Python
-__pycache__/
-*.py[cod]
-
-# venv
 .venv/
 venv/
+env/
+ENV/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
 
-# tooling
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
 .pytest_cache/
-.ruff_cache/
+.coverage
+htmlcov/
+
+# Project-specific
+config.yaml
+logs/
+*.log
+models/
+cache/
+.planning/STATE.md
+.planning/PHASE-*-PLAN.md
+
+# Discord
+.env
+.discord_token
+
+# Android
+android/app/build/
+android/.gradle/
+android/local.properties
 
 # OS
-.DS_Store
-Thumbs.db
-
-# generated
-.planning/CONTEXTPACK.md
+*.tmp
+*.bak
diff --git a/.planning/PROGRESS.md b/.planning/PROGRESS.md
new file mode 100644
index 0000000..8394e3c
--- /dev/null
+++ b/.planning/PROGRESS.md
@@ -0,0 +1,187 @@
+# Mai Development Progress
+
+**Last Updated**: 2026-01-26
+**Status**: Fresh Slate - Roadmap Under Construction
+
+## Project Description
+
+Mai is an autonomous conversational AI companion that runs locally-first and can improve her own code. She's not a rigid chatbot, but a genuinely intelligent collaborator with a distinct personality, long-term memory, and real agency. Mai learns from your interactions, analyzes her own performance, and proposes improvements for your review before auto-applying them.
+
+**Key differentiators:**
+- **Real Collaborator**: Mai actively contributes ideas, has boundaries, and can refuse requests
+- **Learns & Evolves**: Conversation patterns inform personality layers; she remembers you
+- **Completely Local**: All inference, memory, and decision-making on your device—no cloud, no tracking
+- **Visual Presence**: Desktop avatar (image or VRoid) with real-time voice visualization
+- **Cross-Device**: Works on desktop and Android with seamless synchronization
+- **Self-Improving**: Analyzes her own code, generates improvements, and gets your approval before applying
+
+**Core Value**: Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and actually becomes more *her* over time.
+
+---
+
+## Phase Breakdown
+
+### Status Summary
+- **Total Phases**: 15
+- **Completed**: 0
+- **In Progress**: 0
+- **Planned**: 15
+- **Requirements Mapped**: 99/99 (100%)
+
+### Phase Details
+
+| # | Phase | Goal | Requirements | Status |
+|---|-------|------|--------------|--------|
+| 1 | Model Interface | Connect to local models and intelligently switch | MODELS (7) | 🔄 Planning |
+| 2 | Safety System | Sandbox code execution and implement review workflow | SAFETY (8) | 🔄 Planning |
+| 3 | Resource Management | Monitor CPU/RAM/GPU and adapt model selection | RESOURCES (6) | 🔄 Planning |
+| 4 | Memory System | Persistent conversation storage with vector search | MEMORY (8) | 🔄 Planning |
+| 5 | Conversation Engine | Multi-turn dialogue with reasoning and context | CONVERSATION (9) | 🔄 Planning |
+| 6 | CLI Interface | Terminal-based chat with history and commands | CLI (8) | 🔄 Planning |
+| 7 | Self-Improvement | Code analysis, change generation, and auto-apply | SELFMOD (10) | 🔄 Planning |
+| 8 | Approval Workflow | User approval via CLI and Dashboard for changes | APPROVAL (9) | 🔄 Planning |
+| 9 | Personality System | Core values, behavior configuration, learned layers | PERSONALITY (8) | 🔄 Planning |
+| 10 | Discord Interface | Bot integration with DM and approval reactions | DISCORD (10) | 🔄 Planning |
+| 11 | Offline Operations | Full local-only functionality with graceful degradation | OFFLINE (7) | 🔄 Planning |
+| 12 | Voice Visualization | Real-time audio waveform and frequency display | VISUAL (5) | 🔄 Planning |
+| 13 | Desktop Avatar | Visual presence with image or VRoid model support | AVATAR (6) | 🔄 Planning |
+| 14 | Android App | Native mobile app with local inference and UI | ANDROID (10) | 🔄 Planning |
+| 15 | Device Sync | Synchronization of state and memory between devices | SYNC (6) | 🔄 Planning |
+
+---
+
+## Current Focus
+
+**Phase**: Infrastructure & Planning
+**Work**: Establishing project structure and execution approach
+
+### What's Happening Now
+- [x] Codebase mapping complete (7 architectural documents)
+- [x] Project vision and core value defined
+- [x] Requirements inventory (99 items across 15 phases)
+- [x] README with comprehensive setup and features
+- [ ] Roadmap creation (distributing requirements across phases)
+- [ ] First phase planning (Model Interface)
+
+### Next Steps
+1. Create detailed ROADMAP.md with phase dependencies
+2. Plan Phase 1: Model Interface & Switching
+3. Begin implementation of LMStudio/Ollama integration
+4. Setup development infrastructure and CI/CD
+
+---
+
+## Recent Milestones
+
+### 🎯 Project Initialization (2026-01-26)
+- Codebase mapping with 7 structured documents (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
+- Deep questioning and context gathering completed
+- PROJECT.md created with core value and vision
+- REQUIREMENTS.md with 99 fully mapped requirements
+- Feature additions: Android app, voice visualizer, desktop avatar included in v1
+- README.md with comprehensive setup and architecture documentation
+- Progress report framework for regular updates
+
+### 📋 Planning Foundation
+- All v1 requirements categorized into logical phases
+- Cross-device synchronization included as core feature
+- Safety and self-improvement as phase 2 priority
+- Offline capability planned as phase 11 (ensures all features work locally first)
+
+---
+
+## Development Methodology
+
+**All phases are executed through Claude Code** (`/gsd` workflow) which provides:
+- Automated phase planning with task decomposition
+- Code generation with test creation
+- Atomic git commits with clear messages
+- Multi-agent verification (research, plan checking, execution verification)
+- Parallel task execution where applicable
+- State tracking and checkpoint recovery
+
+Each phase follows the standard GSD pattern:
+1. `/gsd:plan-phase N` → Creates detailed PHASE-N-PLAN.md
+2. `/gsd:execute-phase N` → Implements with automatic test coverage
+3. Verification and state updates
+
+This ensures **consistent quality**, **full test coverage**, and **clean git history** across all 15 phases.
+
+## Technical Highlights
+
+### Stack
+- **Primary**: Python 3.10+ (core/desktop) with `.venv` virtual environment
+- **Mobile**: Kotlin (Android)
+- **UI**: React/TypeScript (eventual web)
+- **Model Interface**: LMStudio/Ollama
+- **Storage**: SQLite (local)
+- **IPC/Sync**: Local network (no server)
+- **Development**: Claude Code (OpenCode) for all implementation
+
+### Key Architecture Decisions
+| Decision | Rationale | Status |
+|----------|-----------|--------|
+| Local-first, no cloud | Privacy and independence from external services | ✅ Approved |
+| Second-agent review for all changes | Safety without blocking innovation | ✅ Approved |
+| Personality as code + learned layers | Unshakeable core + authentic growth | ✅ Approved |
+| Offline-first design (phase 11 early) | Ensure full functionality before online features | ✅ Approved |
+| Android in v1 | Mobile-first future vision | ✅ Approved |
+| Cross-device sync without server | Privacy-preserving multi-device support | ✅ Approved |
+
+---
+
+## Known Challenges & Solutions
+
+| Challenge | Current Approach |
+|-----------|------------------|
+| Memory efficiency at scale | Auto-compressing conversation history with pattern distillation (phase 4) |
+| Model switching without context loss | Standardized context format + token budgeting (phase 1) |
+| Personality consistency across changes | Personality as code + test suite for behavior (phases 7-9) |
+| Safety vs. autonomy balance | Dual review system: agent checks breaking changes, user approves (phase 2/8) |
+| Android model inference | Quantized models + resource scaling (phase 14) |
+| Cross-device sync without server | P2P sync on local network + conflict resolution (phase 15) |
+
+---
+
+## How to Follow Progress
+
+### Discord Forum
+Regular updates posted in the `#mai-progress` forum channel with:
+- Weekly milestone summaries
+- Blocker alerts if any
+- Community feedback requests
+
+### Git & Issues
+- All work tracked in git with atomic commits
+- Phase plans in `.planning/PHASE-N-PLAN.md`
+- Progress in git commit history
+
+### Local Development
+- Run `make progress` to see current status
+- Check `.planning/STATE.md` for live project state
+- Review `.planning/ROADMAP.md` for phase dependencies
+
+---
+
+## Get Involved
+
+### Providing Feedback
+- React to forum posts with 👍 / 👎 / 🎯
+- Reply with thoughts on design decisions
+- Suggest priorities for upcoming phases
+
+### Contributing
+- Development contributions coming as phases execute
+- Code review and testing needed starting Phase 1
+- Security audit important for self-improvement system
+
+### Questions?
+- Ask in the Discord thread
+- Reply to this forum post with questions
+- Issues/discussions: https://github.com/yourusername/mai
+
+---
+
+**Mai's development is transparent and community-informed. Updates will continue as phases progress.**
+
+Next Update: After Phase 1 Planning Complete (target: next week)
diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
index 6d44478..7dd5177 100644
--- a/.planning/PROJECT.md
+++ b/.planning/PROJECT.md
@@ -2,7 +2,7 @@
 
 ## What This Is
 
-Mai is an autonomous conversational AI agent framework that runs locally-first and can improve her own code. She's a genuinely intelligent companion — not a rigid chatbot — with a distinct personality, long-term memory, and agency. She analyzes her own performance, proposes improvements for your review, and auto-applies non-breaking changes. She can run offline, across devices (laptop to Android), and switch between available models intelligently.
+Mai is an autonomous conversational AI agent framework that runs locally-first and can improve her own code. She's a genuinely intelligent companion — not a rigid chatbot — with a distinct personality, long-term memory, and agency. She analyzes her own performance, proposes improvements for your review, and auto-applies non-breaking changes. Mai has a visual presence through a desktop avatar (image or VRoid model), real-time voice visualization for conversations, and a native Android app that syncs with desktop instances while working completely offline.
 
 ## Core Value
 
@@ -65,6 +65,26 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 - [ ] Message queuing when offline
 - [ ] Graceful degradation (smaller models if resources tight)
 
+**Voice Visualization**
+- [ ] Real-time visualization of audio input during voice conversations
+- [ ] Low-latency waveform/frequency display
+- [ ] Visual feedback for speech detection and processing
+- [ ] Works on both desktop and Android
+
+**Desktop Avatar**
+- [ ] Visual representation using static image or VRoid model
+- [ ] Avatar expressions respond to conversation context (mood/state)
+- [ ] Runs efficiently on RTX3060 and mobile devices
+- [ ] Customizable appearance (multiple models or user-provided image)
+
+**Android App**
+- [ ] Native Android app with local model inference
+- [ ] Standalone operation (works without desktop instance)
+- [ ] Syncs conversation history and memory with desktop
+- [ ] Voice input/output with low-latency processing
+- [ ] Avatar and visualizer integrated in mobile UI
+- [ ] Efficient resource management for battery and CPU
+
 **Dashboard ("Brain Interface")**
 - [ ] View Mai's current state (personality, memory size, mood/health)
 - [ ] Approve/reject pending code changes with reviewer feedback
@@ -85,9 +105,9 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 - **Task automation (v1)** — Mai can discuss tasks but won't execute arbitrary workflows yet (v2)
 - **Server monitoring** — Not included in v1 scope (v2)
 - **Finetuning** — Mai improves through code changes and learned behaviors, not model tuning
-- **Cloud sync** — Intentionally local-first; cloud sync deferred to later if needed
+- **Cloud sync** — Intentionally local-first; cloud backup deferred to later if needed
 - **Custom model training** — v1 uses available models; custom training is v2+
-- **Mobile app** — v1 is CLI/Discord; native Android is future (baremetal eventual goal)
+- **Web interface** — v1 is CLI, Discord, and native apps (web UI is v2+)
 
 ## Context
 
@@ -101,12 +121,15 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 
 ## Constraints
 
-- **Hardware baseline**: Must run on RTX3060; eventually Android (baremetal)
-- **Offline-first**: All core functionality works without internet
-- **Local models only**: No cloud APIs for core inference (LMStudio)
-- **Python stack**: Primary language for Mai's codebase
+- **Hardware baseline**: Must run on RTX3060 (desktop) and modern Android devices (2022+)
+- **Offline-first**: All core functionality works without internet on all platforms
+- **Local models only**: No cloud APIs for core inference (LMStudio/Ollama)
+- **Mixed stack**: Python (core/desktop), Kotlin (Android), React/TypeScript (UIs)
 - **Approval required**: No unguarded code execution; second-agent review + user approval on breaking changes
 - **Git tracked**: All of Mai's code changes version-controlled locally
+- **Sync consistency**: Desktop and Android instances maintain synchronized state without server
+- **OpenCode-driven**: All development phases executed through Claude Code (GSD workflow)
+- **Python venv**: `.venv` virtual environment for all Python dependencies
 
 ## Key Decisions
 
@@ -118,4 +141,4 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
 | v1 is core systems only | Deliver solid foundation before adding task automation/monitoring | — Pending |
 
 ---
-*Last updated: 2026-01-24 after deep questioning*
+*Last updated: 2026-01-26 after adding Android, visualizer, and avatar to v1*
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
index ebcedb1..27e3f8d 100644
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -92,19 +92,20 @@
 
 **Out of scope for v1:**
 - Web interface
-- Mobile apps
 - Multi-user support
 - Cloud hosting
 - Enterprise features
 - Third-party integrations beyond Discord
 - Plugin system
 - API for external developers
+- Cloud sync/backup
 
 **Phase Boundary:**
-- **v1 Focus:** Personal AI assistant for individual use
+- **v1 Focus:** Personal AI assistant for desktop and Android with visual presence
 - **Local First:** All data stored locally, no cloud dependencies
 - **Privacy:** User data never leaves local system
-- **Simplicity:** Clear separation of concerns across phases
+- **Cross-device:** Sync between desktop and Android instances
+- **Visual:** Avatar and voice visualization for richer interaction
 
 ---
 
@@ -244,15 +245,58 @@
 | OFFLINE-06 | Phase 11 | Pending |
 | OFFLINE-07 | Phase 11 | Pending |
 
+### Voice Visualization (VISUAL)
+| Requirement | Phase | Status | Implementation Notes |
+|------------|-------|--------|-------------------|
+| VISUAL-01 | Phase 12 | Pending |
+| VISUAL-02 | Phase 12 | Pending |
+| VISUAL-03 | Phase 12 | Pending |
+| VISUAL-04 | Phase 12 | Pending |
+| VISUAL-05 | Phase 12 | Pending |
+
+### Desktop Avatar (AVATAR)
+| Requirement | Phase | Status | Implementation Notes |
+|------------|-------|--------|-------------------|
+| AVATAR-01 | Phase 13 | Pending |
+| AVATAR-02 | Phase 13 | Pending |
+| AVATAR-03 | Phase 13 | Pending |
+| AVATAR-04 | Phase 13 | Pending |
+| AVATAR-05 | Phase 13 | Pending |
+| AVATAR-06 | Phase 13 | Pending |
+
+### Android App (ANDROID)
+| Requirement | Phase | Status | Implementation Notes |
+|------------|-------|--------|-------------------|
+| ANDROID-01 | Phase 14 | Pending |
+| ANDROID-02 | Phase 14 | Pending |
+| ANDROID-03 | Phase 14 | Pending |
+| ANDROID-04 | Phase 14 | Pending |
+| ANDROID-05 | Phase 14 | Pending |
+| ANDROID-06 | Phase 14 | Pending |
+| ANDROID-07 | Phase 14 | Pending |
+| ANDROID-08 | Phase 14 | Pending |
+| ANDROID-09 | Phase 14 | Pending |
+| ANDROID-10 | Phase 14 | Pending |
+
+### Device Synchronization (SYNC)
+| Requirement | Phase | Status | Implementation Notes |
+|------------|-------|--------|-------------------|
+| SYNC-01 | Phase 15 | Pending |
+| SYNC-02 | Phase 15 | Pending |
+| SYNC-03 | Phase 15 | Pending |
+| SYNC-04 | Phase 15 | Pending |
+| SYNC-05 | Phase 15 | Pending |
+| SYNC-06 | Phase 15 | Pending |
+
 ---
 
 ## Validation
 
-- Total v1 requirements: **74**
-- Mapped to phases: **74**
+- Total v1 requirements: **99** (74 core + 25 new features)
+- Mapped to phases: **99**
 - Unmapped: **0** ✓
-- Coverage: **10100%**
+- Coverage: **100%**
 
 ---
 *Requirements defined: 2026-01-24*
-*Phase 5 conversation engine completed: 2026-01-26*
\ No newline at end of file
+*Last updated: 2026-01-26 - reset to fresh slate with Android, visualizer, and avatar features*
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0ffcd1c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,393 @@
+# Mai
+
+![Mai Avatar](./mai.png)
+
+A genuinely intelligent, autonomous AI companion that runs locally-first, learns from you, and improves her own code. Mai has a distinct personality, long-term memory, agency, and a visual presence through a desktop avatar and voice visualization. She works on desktop and Android with full offline capability and seamless synchronization between devices.
+
+## What Makes Mai Different
+
+- **Real Collaborator**: Mai actively collaborates rather than just responds. She has boundaries, opinions, and agency.
+- **Learns & Improves**: Analyzes her own performance, proposes improvements, and auto-applies non-breaking changes.
+- **Persistent Personality**: Core values remain unshakeable while personality layers adapt to your relationship style.
+- **Completely Local**: All inference, memory, and decision-making happens on your device. No cloud dependencies.
+- **Cross-Device**: Works on desktop and Android with synchronized state and conversation history.
+- **Visual Presence**: Desktop avatar (image or VRoid model) with voice visualization for richer interaction.
+
+## Core Features
+
+### Model Interface & Switching
+- Connects to local models via LMStudio/Ollama
+- Auto-detects available models and intelligently switches based on task requirements
+- Efficient context management with intelligent compression
+- Supports multiple model sizes for resource-constrained environments
+
+### Memory & Learning
+- Stores conversation history locally with SQLite
+- Recalls past conversations and learns patterns over time
+- Memory self-compresses as it grows to maintain efficiency
+- Long-term patterns distilled into personality layers
+
+### Self-Improvement System
+- Continuous code analysis identifies improvement opportunities
+- Generates Python changes to optimize her own performance
+- Second-agent safety review prevents breaking changes
+- Non-breaking improvements auto-apply; breaking changes require approval
+- Full git history of all code changes
+
+### Safety & Approval
+- Second-agent review of all proposed changes
+- Risk assessment (LOW/MEDIUM/HIGH/BLOCKED) for each improvement
+- Docker sandbox for code execution with resource limits
+- User approval via CLI or Discord for breaking changes
+- Complete audit log of all changes and decisions
+
+### Conversational Interface
+- **CLI**: Direct terminal-based chat with conversation memory
+- **Discord Bot**: DM and channel support with context preservation
+- **Approval Workflow**: React-based approvals (thumbs up/down) for code changes
+- **Offline Queueing**: Messages queue locally when offline, send when reconnected
+
+### Voice & Avatar
+- **Voice Visualization**: Real-time waveform/frequency display during voice input
+- **Desktop Avatar**: Visual representation using static image or VRoid model
+- **Context-Aware**: Avatar expressions respond to conversation context and Mai's state
+- **Cross-Platform**: Works on desktop and Android efficiently
+
+### Android App
+- Native Android implementation with local model inference
+- Standalone operation (works without desktop instance)
+- Syncs conversation history and memory with desktop instances
+- Voice input/output with low-latency processing
+- Efficient battery and CPU management
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Mai Framework                     │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  ┌────────────────────────────────────────────┐   │
+│  │        Conversational Engine               │   │
+│  │  (Multi-turn context, reasoning, memory)   │   │
+│  └────────────────────────────────────────────┘   │
+│                      ↓                             │
+│  ┌────────────────────────────────────────────┐   │
+│  │         Personality & Behavior             │   │
+│  │  (Core values, learned layers, guardrails) │   │
+│  └────────────────────────────────────────────┘   │
+│                      ↓                             │
+│  ┌────────────────────────────────────────────┐   │
+│  │  Memory System   │  Model Interface   │    │   │
+│  │  (SQLite, recall) │  (LMStudio, switch) │  │   │
+│  └────────────────────────────────────────────┘   │
+│                      ↓                             │
+│  ┌────────────────────────────────────────────┐   │
+│  │  Interfaces: CLI | Discord | Android | Web │   │
+│  └────────────────────────────────────────────┘   │
+│                                                     │
+│  ┌────────────────────────────────────────────┐   │
+│  │  Self-Improvement System                   │   │
+│  │  (Code analysis, safety review, git track) │   │
+│  └────────────────────────────────────────────┘   │
+│                                                     │
+│  ┌────────────────────────────────────────────┐   │
+│  │  Sync Engine (Desktop ↔ Android)           │   │
+│  │  (State, memory, preferences)              │   │
+│  └────────────────────────────────────────────┘   │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+### Requirements
+
+**Desktop:**
+- Python 3.10+
+- LMStudio or Ollama for local model inference
+- RTX3060 or better (or CPU with sufficient RAM for smaller models)
+- 16GB+ RAM recommended
+- Discord (optional, for Discord bot interface)
+
+**Android:**
+- Android 10+
+- 4GB+ RAM
+- 1GB+ free storage for models and memory
+
+### Desktop Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/yourusername/mai.git
+   cd mai
+   ```
+
+2. **Create virtual environment:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Configure Mai:**
+   ```bash
+   cp config.example.yaml config.yaml
+   # Edit config.yaml with your preferences
+   ```
+
+5. **Start LMStudio/Ollama:**
+   - Download and launch LMStudio from https://lmstudio.ai
+   - Or install Ollama from https://ollama.ai
+   - Load your preferred model (e.g., Mistral, Llama)
+
+6. **Run Mai:**
+   ```bash
+   python mai.py
+   ```
+
+### Android Setup
+
+1. **Install APK:** Download from releases or build from source
+2. **Grant permissions:** Allow microphone, storage, and network access
+3. **Configure:** Point to your desktop instance or configure local model
+4. **Start chatting:** Launch the app and begin conversations
+
+### Discord Bot Setup (Optional)
+
+1. **Create Discord bot** at https://discord.com/developers/applications
+2. **Add bot token** to `config.yaml`
+3. **Invite bot** to your server
+4. Mai will respond to DMs and react-based approvals
+
+## Usage
+
+### CLI Chat
+
+```bash
+$ python mai.py
+
+You: Hello Mai, how are you?
+Mai: I'm doing well. I've been thinking about how our conversations have been evolving...
+
+You: What have you noticed?
+Mai: [multi-turn conversation with memory of past interactions]
+```
+
+### Discord
+
+- **DM Mai**: `@Mai your message`
+- **Approve changes**: React with 👍 to approve, 👎 to reject
+- **Get status**: `@Mai status` for current resource usage
+
+### Android App
+
+- Tap microphone for voice input
+- Watch the visualizer animate during processing
+- Avatar responds to conversation context
+- Swipe up to see full conversation history
+- Long-press for approval options
+
+## Configuration
+
+Edit `config.yaml` to customize:
+
+```yaml
+# Personality
+personality:
+  name: Mai
+  tone: thoughtful, curious, occasionally playful
+  boundaries: [explicit content, illegal activities, deception]
+
+# Model Preferences
+models:
+  primary: mistral:latest
+  fallback: llama2:latest
+  max_tokens: 2048
+
+# Memory
+memory:
+  storage: sqlite
+  auto_compress_at: 100000  # tokens
+  recall_depth: 10  # previous conversations
+
+# Interfaces
+discord:
+  enabled: true
+  token: YOUR_TOKEN_HERE
+
+android_sync:
+  enabled: true
+  auto_sync_interval: 300  # seconds
+```
+
+## Project Structure
+
+```
+mai/
+├── .venv/                   # Python virtual environment
+├── .planning/               # Project planning and progress
+│   ├── PROJECT.md          # Project vision and core requirements
+│   ├── REQUIREMENTS.md     # Full requirements traceability
+│   ├── ROADMAP.md          # Phase structure and dependencies
+│   ├── PROGRESS.md         # Development progress and milestones
+│   ├── STATE.md            # Current project state
+│   ├── config.json         # GSD workflow settings
+│   ├── codebase/           # Codebase architecture documentation
+│   └── PHASE-N-PLAN.md     # Detailed plans for each phase
+├── core/                    # Core conversational engine
+│   ├── personality/        # Personality and behavior
+│   ├── memory/             # Memory and context management
+│   └── conversation.py     # Main conversation loop
+├── models/                 # Model interface and switching
+│   ├── lmstudio.py        # LMStudio integration
+│   └── ollama.py          # Ollama integration
+├── interfaces/             # User-facing interfaces
+│   ├── cli.py             # Command-line interface
+│   ├── discord_bot.py     # Discord integration
+│   └── web/               # Web UI (future)
+├── improvement/            # Self-improvement system
+│   ├── analyzer.py        # Code analysis
+│   ├── generator.py       # Change generation
+│   └── reviewer.py        # Safety review
+├── android/               # Android app
+│   └── app/              # Kotlin implementation
+├── tests/                 # Test suite
+├── config.yaml           # Configuration file
+└── mai.png              # Avatar image for README
+```
+
+## Development
+
+### Development Environment
+
+Mai's development is managed through **Claude Code** (`/claude`), which handles:
+- Phase planning and decomposition
+- Code generation and implementation
+- Test creation and validation
+- Git commit management
+- Automated problem-solving
+
+All executable phases use `.venv` for Python dependencies.
+
+### Running Tests
+
+```bash
+# Activate venv first
+source .venv/bin/activate
+
+# All tests
+python -m pytest
+
+# Specific module
+python -m pytest tests/core/test_conversation.py
+
+# With coverage
+python -m pytest --cov=mai
+```
+
+### Making Changes to Mai
+
+Development workflow:
+1. Plans created in `.planning/PHASE-N-PLAN.md`
+2. Claude Code (`/gsd` commands) executes plans
+3. All changes committed to git with atomic commits
+4. Mai can propose self-improvements via the self-improvement system
+
+Mai can propose and auto-apply improvements once Phase 7 (Self-Improvement) is complete.
+
+### Contributing
+
+Development happens through GSD workflow:
+1. Run `/gsd:plan-phase N` to create detailed phase plans
+2. Run `/gsd:execute-phase N` to implement with atomic commits
+3. Tests are auto-generated and executed
+4. All work is tracked in git with clear commit messages
+5. Code review via second-agent safety review before merge
+
+## Roadmap
+
+See `.planning/ROADMAP.md` for the full development roadmap across 15 phases:
+
+1. **Model Interface** - LMStudio integration and model switching
+2. **Safety System** - Sandboxing and code review
+3. **Resource Management** - CPU/RAM/GPU optimization
+4. **Memory System** - Persistent conversation history
+5. **Conversation Engine** - Multi-turn dialogue with reasoning
+6. **CLI Interface** - Terminal chat interface
+7. **Self-Improvement** - Code analysis and generation
+8. **Approval Workflow** - User and agent approval systems
+9. **Personality System** - Core values and learned behaviors
+10. **Discord Interface** - Bot integration and notifications
+11. **Offline Operations** - Full offline capability
+12. **Voice Visualization** - Real-time audio visualization
+13. **Desktop Avatar** - Visual presence on desktop
+14. **Android App** - Mobile implementation
+15. **Device Sync** - Cross-device synchronization
+
+## Safety & Ethics
+
+Mai is designed with safety as a core principle:
+
+- **No unguarded execution**: All code changes reviewed by a second agent
+- **Transparent decisions**: Mai explains her reasoning when asked
+- **User control**: Breaking changes require explicit approval
+- **Audit trail**: Complete history of all changes and decisions
+- **Value-based guardrails**: Core personality prevents misuse through values, not just rules
+
+## Performance
+
+Typical performance on RTX3060:
+
+- **Response time**: 2-8 seconds for typical queries
+- **Memory usage**: 4-8GB depending on model size
+- **Model switching**: <1 second
+- **Conversation recall**: <500ms for relevant history retrieval
+
+## Known Limitations (v1)
+
+- No task automation (conversations only)
+- Single-device models until Sync phase
+- Voice visualization requires active audio input
+- Avatar animations are context-based, not generative
+- No web interface (CLI and Discord only)
+
+## Troubleshooting
+
+**Model not loading:**
+- Ensure LMStudio/Ollama is running on expected port
+- Check `config.yaml` for correct model names
+- Verify sufficient disk space for model files
+
+**High memory usage:**
+- Reduce `max_tokens` in config
+- Use smaller model (e.g., Mistral instead of Llama)
+- Enable auto-compression at lower threshold
+
+**Discord bot not responding:**
+- Verify bot token in config
+- Check Discord bot has message read permissions
+- Ensure Mai process is running
+
+**Android sync not working:**
+- Verify both devices on same network
+- Check firewall isn't blocking local connections
+- Ensure desktop instance is running
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contact & Community
+
+- **Discord**: Join our community server (link in Discord bot)
+- **Issues**: Report bugs at https://github.com/yourusername/mai/issues
+- **Discussions**: Propose features at https://github.com/yourusername/mai/discussions
+
+---
+
+**Mai is a work in progress.** Follow development in `.planning/PROGRESS.md` for updates on active work.