diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..8b3845a0
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to Voicebox will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-25
+
+### Added
+
+#### Core Features
+- **Voice Cloning** - Clone voices from audio samples using Qwen3-TTS (1.7B and 0.6B models)
+- **Voice Profile Management** - Create, edit, and organize voice profiles with multiple samples
+- **Speech Generation** - Generate high-quality speech from text using cloned voices
+- **Generation History** - Track all generations with search and filtering capabilities
+- **Audio Transcription** - Automatic transcription powered by Whisper
+- **In-App Recording** - Record audio samples directly in the app with waveform visualization
+
+#### Desktop App
+- **Tauri Desktop App** - Native desktop application for macOS, Windows, and Linux
+- **Local Server Mode** - Embedded Python server runs automatically
+- **Remote Server Mode** - Connect to a remote Voicebox server on your network
+- **Auto-Updates** - Automatic update notifications and installation
+
+#### API
+- **REST API** - Full REST API for voice synthesis and profile management
+- **OpenAPI Documentation** - Interactive API docs at `/docs` endpoint
+- **Type-Safe Client** - Auto-generated TypeScript client from OpenAPI schema
+
+#### Technical
+- **Voice Prompt Caching** - Fast regeneration with cached voice prompts
+- **Multi-Sample Support** - Combine multiple audio samples for better voice quality
+- **GPU/CPU/MPS Support** - Automatic device detection and optimization
+- **Model Management** - Lazy loading and VRAM management
+- **SQLite Database** - Local data persistence
+
+### Technical Details
+
+- Built with Tauri v2 (Rust + React)
+- FastAPI backend with async Python
+- TypeScript frontend with React Query and Zustand
+- Qwen3-TTS for voice cloning
+- Whisper for transcription
+
+### Platform Support
+
+- macOS (Apple Silicon and Intel)
+- Windows
+- Linux (AppImage)
+
+---
+
+## [Unreleased]
+
+### Planned
+- Real-time streaming synthesis
+- Conversation mode with multiple speakers
+- Voice effects (pitch shift, reverb, M3GAN-style)
+- Timeline-based audio editor
+- Additional voice models (XTTS, Bark)
+- Voice design from text descriptions
+- Project system for saving sessions
+- Plugin architecture
+
+---
+
+[0.1.0]: https://github.com/jamiepine/voicebox/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..dbadfd95
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,252 @@
+# Contributing to Voicebox
+
+Thank you for your interest in contributing to Voicebox! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Welcome newcomers and help them learn
+- Focus on constructive feedback
+- Respect different viewpoints and experiences
+
+## Getting Started
+
+### Prerequisites
+
+- [Bun](https://bun.sh) - Package manager
+- [Rust](https://rustup.rs) - For Tauri desktop app
+- [Python 3.11+](https://python.org) - For backend
+- Git
+
+### Development Setup
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/voicebox.git
+   cd voicebox
+   ```
+
+2. **Install dependencies**
+   ```bash
+   bun install
+   cd backend && pip install -r requirements.txt && cd ..
+   ```
+
+3. **Set up the database**
+   ```bash
+   cd backend
+   python -c "from database import init_db; init_db()"
+   ```
+
+4. **Start development**
+   ```bash
+   # Terminal 1: Backend server
+   bun run dev:server
+   
+   # Terminal 2: Desktop app
+   bun run dev
+   ```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Your Changes
+
+- Write clean, readable code
+- Follow existing code style
+- Add comments for complex logic
+- Update documentation as needed
+
+### 3. Test Your Changes
+
+- Test manually in the app
+- Ensure backend API endpoints work
+- Check for TypeScript/Python errors
+- Verify UI components render correctly
+
+### 4. Commit Your Changes
+
+Write clear, descriptive commit messages:
+
+```bash
+git commit -m "Add feature: voice profile export"
+git commit -m "Fix: audio playback stops after 30 seconds"
+```
+
+### 5. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a pull request on GitHub with:
+- Clear description of changes
+- Screenshots (for UI changes)
+- Reference to related issues
+
+## Code Style
+
+### TypeScript/React
+
+- Use TypeScript strict mode
+- Follow React best practices
+- Use functional components with hooks
+- Prefer named exports
+- Format with Biome (runs automatically)
+
+```typescript
+// Good
+export function ProfileCard({ profile }: { profile: Profile }) {
+  return <div>{profile.name}</div>;
+}
+
+// Avoid
+export const ProfileCard = (props) => { ... }
+```
+
+### Python
+
+- Follow PEP 8 style guide
+- Use type hints
+- Use async/await for I/O operations
+- Format with Black (if configured)
+
+```python
+# Good
+async def create_profile(name: str, language: str) -> Profile:
+    """Create a new voice profile."""
+    ...
+
+# Avoid
+def create_profile(name, language):
+    ...
+```
+
+### Rust
+
+- Follow Rust conventions
+- Use meaningful variable names
+- Handle errors explicitly
+- Format with `rustfmt`
+
+## Project Structure
+
+```
+voicebox/
+├── app/              # Shared React frontend
+│   └── src/
+│       ├── components/   # UI components
+│       ├── lib/          # Utilities and API client
+│       └── hooks/        # React hooks
+├── backend/          # Python FastAPI server
+│   ├── main.py       # API routes
+│   ├── tts.py        # Voice synthesis
+│   └── ...
+├── tauri/            # Desktop app wrapper
+│   └── src-tauri/    # Rust backend
+└── scripts/          # Build scripts
+```
+
+## Areas for Contribution
+
+### 🐛 Bug Fixes
+
+- Check existing issues for bugs to fix
+- Test your fix thoroughly
+- Add tests if possible
+
+### ✨ New Features
+
+- Check the roadmap in README.md
+- Discuss major features in an issue first
+- Keep features focused and well-scoped
+
+### 📚 Documentation
+
+- Improve README clarity
+- Add code comments
+- Write API documentation
+- Create tutorials or guides
+
+### 🎨 UI/UX Improvements
+
+- Improve accessibility
+- Enhance visual design
+- Optimize performance
+- Add animations/transitions
+
+### 🔧 Infrastructure
+
+- Improve build process
+- Add CI/CD improvements
+- Optimize bundle size
+- Add testing infrastructure
+
+## API Development
+
+When adding new API endpoints:
+
+1. **Add route in `backend/main.py`**
+2. **Create Pydantic models in `backend/models.py`**
+3. **Implement business logic in appropriate module**
+4. **Update OpenAPI schema** (automatic with FastAPI)
+5. **Regenerate TypeScript client:**
+   ```bash
+   bun run generate:api
+   ```
+6. **Update `backend/README.md`** with endpoint documentation
+
+## Testing
+
+Currently, testing is primarily manual. When adding tests:
+
+- **Backend**: Use pytest for Python tests
+- **Frontend**: Use Vitest for React component tests
+- **E2E**: Use Playwright for end-to-end tests (future)
+
+## Pull Request Process
+
+1. **Update documentation** if needed
+2. **Ensure code follows style guidelines**
+3. **Test your changes thoroughly**
+4. **Update CHANGELOG.md** with your changes
+5. **Request review** from maintainers
+
+### PR Checklist
+
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] Changes tested
+- [ ] No breaking changes (or documented)
+- [ ] CHANGELOG.md updated
+
+## Release Process
+
+Releases are managed by maintainers:
+
+1. Version bump in `tauri.conf.json` and `Cargo.toml`
+2. Update CHANGELOG.md
+3. Create git tag: `git tag v0.2.0`
+4. Push tag: `git push --tags`
+5. GitHub Actions builds and releases
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Check existing issues and discussions
+- Review the codebase to understand patterns
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to Voicebox! 🎉
diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md
deleted file mode 100644
index 975b1447..00000000
--- a/CURRENT_STATE.md
+++ /dev/null
@@ -1,447 +0,0 @@
-# voicebox - Current State Overview
-
-**Last Updated:** January 25, 2026  
-**Status:** ✅ MVP Core Features Working - Voice generation from Tauri app successful!
-
----
-
-## 🎯 What We Have
-
-### ✅ **Fully Implemented & Working**
-
-#### **Backend (Python FastAPI)**
-- **Voice Profile Management**
-  - Create, read, update, delete profiles
-  - Add multiple audio samples per profile
-  - Multi-reference voice combination (combines multiple samples)
-  - Profile storage in SQLite + file system (`data/profiles/`)
-  
-- **Voice Generation**
-  - Qwen3-TTS model integration (1.7B and 0.6B support)
-  - Automatic model downloading from HuggingFace Hub
-  - Voice prompt caching for instant re-generation
-  - Support for English and Chinese
-  - Seed-based reproducibility
-  - GPU/CPU/MPS device detection
-  
-- **Generation History**
-  - Full CRUD operations
-  - Search by text content
-  - Filter by profile
-  - Pagination support
-  - Statistics endpoint
-  - Audio file storage (`data/generations/`)
-  
-- **Audio Transcription**
-  - Whisper integration for speech-to-text
-  - Language detection/selection
-  - Used for reference text extraction from samples
-  
-- **Database**
-  - SQLite with SQLAlchemy ORM
-  - Tables: `profiles`, `profile_samples`, `generations`, `projects` (ready for future)
-  - Automatic schema initialization
-  
-- **API Endpoints**
-  - RESTful API with FastAPI
-  - OpenAPI schema generation
-  - CORS enabled
-  - Health check endpoint
-  - File serving for audio files
-
-#### **Frontend (React + TypeScript + Tauri)**
-- **Voice Profile UI**
-  - Profile list with cards
-  - Create/edit profile dialog
-  - Upload audio samples with transcription
-  - Sample management (view/delete)
-  - Profile detail view
-  
-- **Generation UI**
-  - Form with profile selection
-  - Text input (up to 5000 chars)
-  - Language selection (en/zh)
-  - Optional seed input
-  - Loading states and error handling
-  
-- **History UI**
-  - Table view with pagination
-  - Search functionality
-  - Play audio inline
-  - Download audio files
-  - Delete generations
-  
-- **Server Settings**
-  - Connection form (local/remote mode)
-  - Server status display
-  - Health check integration
-  
-- **State Management**
-  - React Query for server state
-  - Zustand for client state (server URL, connection status)
-  - Type-safe API client
-  
-- **UI Components**
-  - shadcn/ui component library
-  - Tailwind CSS styling
-  - Responsive design
-  - Toast notifications
-  - Form validation with Zod
-
-#### **Tauri Desktop App**
-- **Rust Backend**
-  - Sidecar management for Python server
-  - Start/stop server commands
-  - Remote mode support (0.0.0.0 binding)
-  - Process lifecycle management
-  
-- **Build System**
-  - Tauri v2 configuration
-  - Platform-specific builds
-  - Dev tools in debug mode
-
----
-
-## 🏗️ Architecture
-
-### **Project Structure**
-```
-voicebox/
-├── app/                    # Shared React frontend
-│   ├── src/
-│   │   ├── components/    # React components
-│   │   │   ├── VoiceProfiles/  ✅ Complete
-│   │   │   ├── Generation/     ✅ Complete
-│   │   │   ├── History/        ✅ Complete
-│   │   │   ├── ServerSettings/ ✅ Complete
-│   │   │   └── AudioStudio/    📦 Placeholder (future)
-│   │   ├── lib/
-│   │   │   ├── api/       # Type-safe API client ✅
-│   │   │   ├── hooks/     # React Query hooks ✅
-│   │   │   └── utils/     # Utilities ✅
-│   │   └── stores/        # Zustand stores ✅
-│
-├── backend/               # Python FastAPI server
-│   ├── main.py           # FastAPI app + routes ✅
-│   ├── models.py         # Pydantic models ✅
-│   ├── database.py       # SQLAlchemy ORM ✅
-│   ├── profiles.py        # Profile management ✅
-│   ├── history.py         # History management ✅
-│   ├── tts.py            # Qwen3-TTS integration ✅
-│   ├── transcribe.py     # Whisper integration ✅
-│   ├── studio.py         # Audio studio (future)
-│   └── utils/
-│       ├── audio.py      # Audio processing ✅
-│       ├── cache.py      # Voice prompt caching ✅
-│       └── validation.py # Validation helpers ✅
-│
-├── tauri/                # Tauri desktop wrapper
-│   ├── src/             # React entry point ✅
-│   └── src-tauri/       # Rust backend ✅
-│       └── src/main.rs  # Sidecar management ✅
-│
-├── data/                 # User data directory
-│   ├── profiles/         # Profile audio samples
-│   ├── generations/      # Generated audio files
-│   ├── cache/            # Cached voice prompts
-│   └── voicebox.db       # SQLite database
-│
-└── scripts/              # Build & generation scripts
-    ├── generate-api.sh   # OpenAPI client generation
-    └── build-server.sh   # Python binary build
-```
-
-### **Data Flow**
-
-```
-User Action (Tauri App)
-    ↓
-React Component (Form Submit)
-    ↓
-React Query Hook (useGeneration)
-    ↓
-API Client (apiClient.generateSpeech)
-    ↓
-HTTP Request → FastAPI Backend
-    ↓
-Backend Route Handler (/generate)
-    ↓
-Business Logic:
-  1. Get profile from DB
-  2. Create voice prompt (with caching)
-  3. Generate audio with Qwen3-TTS
-  4. Save audio file
-  5. Create history entry
-    ↓
-Response (GenerationResponse)
-    ↓
-React Query Cache Update
-    ↓
-UI Refresh (History table updates)
-```
-
-### **Key Technologies**
-
-| Layer | Technology | Purpose |
-|-------|-----------|---------|
-| **Desktop Framework** | Tauri v2 | Native desktop app wrapper |
-| **Frontend Framework** | React 18 | UI components |
-| **Language** | TypeScript | Type safety |
-| **Styling** | Tailwind CSS | Utility-first CSS |
-| **UI Components** | shadcn/ui | Component library |
-| **State Management** | React Query + Zustand | Server & client state |
-| **Form Handling** | React Hook Form + Zod | Form validation |
-| **Backend Framework** | FastAPI | Async REST API |
-| **Database** | SQLite + SQLAlchemy | Data persistence |
-| **ML Models** | Qwen3-TTS + Whisper | Voice cloning + transcription |
-| **Audio Processing** | librosa + soundfile | Audio I/O and processing |
-| **Package Manager** | Bun | Fast JS/TS package management |
-| **Build Tool** | Vite | Frontend bundling |
-
----
-
-## 🔑 Key Features & Capabilities
-
-### **1. Voice Profile System**
-- **Multi-sample support**: Add multiple audio samples per profile
-- **Automatic combination**: Multiple samples are combined for better quality
-- **Voice prompt caching**: Re-use voice prompts for instant re-generation
-- **Audio validation**: Ensures samples meet quality requirements
-
-### **2. Generation Pipeline**
-- **Lazy model loading**: Model loads on first use
-- **Device detection**: Automatically uses GPU if available
-- **Caching layer**: Voice prompts cached by audio hash + text
-- **Error handling**: Graceful degradation and clear error messages
-
-### **3. History & Search**
-- **Full-text search**: Search generations by text content
-- **Pagination**: Efficient loading of large histories
-- **Audio playback**: Inline audio player
-- **File management**: Download and delete operations
-
-### **4. Server/Client Architecture**
-- **Local mode**: Backend runs alongside Tauri app
-- **Remote mode**: Connect to remote GPU machine
-- **One-click server**: Start server from UI
-- **Connection management**: Persistent server URL storage
-
----
-
-## 📊 Database Schema
-
-### **Tables**
-
-```sql
--- Voice Profiles
-profiles
-  - id (PK, UUID)
-  - name (unique)
-  - description
-  - language (en/zh)
-  - created_at
-  - updated_at
-
--- Profile Samples
-profile_samples
-  - id (PK, UUID)
-  - profile_id (FK → profiles.id)
-  - audio_path
-  - reference_text
-
--- Generations
-generations
-  - id (PK, UUID)
-  - profile_id (FK → profiles.id)
-  - text
-  - language
-  - audio_path
-  - duration (seconds)
-  - seed (optional)
-  - created_at
-
--- Projects (ready for future)
-projects
-  - id (PK, UUID)
-  - name
-  - data (JSON)
-  - created_at
-  - updated_at
-```
-
----
-
-## 🎨 UI Components Status
-
-| Component | Status | Features |
-|-----------|--------|----------|
-| **ProfileList** | ✅ Complete | List, create, empty state |
-| **ProfileCard** | ✅ Complete | Display profile info |
-| **ProfileForm** | ✅ Complete | Create/edit dialog |
-| **ProfileDetail** | ✅ Complete | View samples, add samples |
-| **SampleUpload** | ✅ Complete | File upload + transcription |
-| **GenerationForm** | ✅ Complete | Full generation form |
-| **HistoryTable** | ✅ Complete | Table, search, pagination, play/download |
-| **ConnectionForm** | ✅ Complete | Server URL input |
-| **ServerStatus** | ✅ Complete | Health check display |
-| **AudioStudio** | 📦 Placeholder | Timeline editor (future) |
-
----
-
-## 🔌 API Endpoints
-
-### **Profiles**
-- `POST /profiles` - Create profile
-- `GET /profiles` - List all profiles
-- `GET /profiles/{id}` - Get profile
-- `PUT /profiles/{id}` - Update profile
-- `DELETE /profiles/{id}` - Delete profile
-- `POST /profiles/{id}/samples` - Add sample
-- `GET /profiles/{id}/samples` - List samples
-- `DELETE /profiles/samples/{id}` - Delete sample
-
-### **Generation**
-- `POST /generate` - Generate speech
-
-### **History**
-- `GET /history` - List generations (with filters)
-- `GET /history/{id}` - Get generation
-- `DELETE /history/{id}` - Delete generation
-- `GET /history/stats` - Get statistics
-
-### **Transcription**
-- `POST /transcribe` - Transcribe audio
-
-### **Audio**
-- `GET /audio/{id}` - Serve audio file
-
-### **Health**
-- `GET /health` - Health check with model status
-
-### **Model Management**
-- `POST /models/load` - Load TTS model
-- `POST /models/unload` - Unload TTS model
-
----
-
-## 🚀 What's Next (Planned Features)
-
-### **Phase 2: Advanced Features**
-- [ ] Multi-reference voice combination UI
-- [ ] Batch generation (multiple variations)
-- [ ] Advanced audio normalization
-- [ ] Export options (MP3, OGG, etc.)
-- [ ] M3GAN voice effect
-
-### **Phase 3: Audio Studio**
-- [ ] Timeline-based audio editor
-- [ ] Word-level timestamps
-- [ ] Project system (save/load sessions)
-- [ ] Audio effects and filters
-- [ ] Multi-track editing
-
-### **Phase 4: Voice Design**
-- [ ] Text-to-voice (no reference needed)
-- [ ] Preset voices with style control
-- [ ] Conversation mode (multi-speaker)
-- [ ] Custom audio effects library
-
----
-
-## 📝 Code Quality Standards
-
-- ✅ **Type safety**: TypeScript strict mode, Pydantic models
-- ✅ **Modular architecture**: No files over 500 lines
-- ✅ **Error handling**: Comprehensive error messages
-- ✅ **Caching**: Voice prompt caching for performance
-- ✅ **Database**: SQLAlchemy ORM with proper relationships
-- ✅ **API design**: RESTful with OpenAPI schema
-- ✅ **UI/UX**: Responsive, accessible, loading states
-
----
-
-## 🧪 Testing Status
-
-- ✅ **Manual testing**: Voice generation working end-to-end
-- 📦 **Unit tests**: Not yet implemented
-- 📦 **Integration tests**: Not yet implemented
-- 📦 **E2E tests**: Not yet implemented
-
----
-
-## 📦 Dependencies
-
-### **Backend**
-- FastAPI - Web framework
-- SQLAlchemy - ORM
-- Pydantic - Validation
-- Qwen3-TTS - Voice cloning model
-- Whisper - Speech recognition
-- librosa - Audio processing
-- soundfile - Audio I/O
-- PyTorch - ML framework
-
-### **Frontend**
-- React 18 - UI framework
-- TypeScript - Type safety
-- React Query - Server state
-- Zustand - Client state
-- React Hook Form - Forms
-- Zod - Schema validation
-- Tailwind CSS - Styling
-- shadcn/ui - Components
-- Lucide React - Icons
-
-### **Desktop**
-- Tauri v2 - Desktop framework
-- Rust - System backend
-
----
-
-## 🎯 Current Capabilities Summary
-
-✅ **Working End-to-End:**
-1. Create voice profiles with audio samples
-2. Generate speech from text using cloned voices
-3. View and manage generation history
-4. Play and download generated audio
-5. Search and filter history
-6. Connect to local or remote backend
-7. Automatic model downloading
-8. Voice prompt caching for speed
-
-🎉 **You just successfully generated voice from the Tauri app!**
-
----
-
-## 🔍 Key Files Reference
-
-### **Backend Core**
-- `backend/main.py` - FastAPI app and routes
-- `backend/tts.py` - Qwen3-TTS model wrapper
-- `backend/profiles.py` - Profile business logic
-- `backend/history.py` - History business logic
-- `backend/database.py` - Database models
-
-### **Frontend Core**
-- `app/src/App.tsx` - Main app component
-- `app/src/lib/api/client.ts` - API client
-- `app/src/lib/hooks/` - React Query hooks
-- `app/src/stores/` - Zustand stores
-
-### **Tauri**
-- `tauri/src-tauri/src/main.rs` - Rust backend
-- `tauri/src/main.tsx` - React entry point
-
----
-
-## 💡 Development Workflow
-
-1. **Start backend**: `bun run dev:server` (or via Tauri)
-2. **Start frontend**: `bun run dev` (Tauri) or `bun run dev:web` (web)
-3. **Generate API client**: `bun run generate:api` (after backend changes)
-4. **Build server binary**: `bun run build:server` (for Tauri bundling)
-
----
-
-**Ready to build more features! 🚀**
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..5eea3a01
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voicebox Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index 86835a64..e482939a 100644
--- a/README.md
+++ b/README.md
@@ -182,14 +182,9 @@ Voicebox aims to be the **one-stop shop for everything voice** — cloning, synt
 
 ## Development
 
-### Prerequisites
+See [SETUP.md](SETUP.md) for detailed setup instructions.
 
-- [Bun](https://bun.sh) (package manager)
-- [Rust](https://rustup.rs) (for Tauri)
-- [Python 3.11+](https://python.org) (for backend)
-- CUDA-capable GPU recommended (CPU inference supported but slower)
-
-### Setup
+### Quick Start
 
 ```bash
 # Clone the repo
@@ -206,6 +201,8 @@ cd backend && pip install -r requirements.txt && cd ..
 bun run dev
 ```
 
+**Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org). CUDA-capable GPU recommended (CPU inference supported but slower).
+
 ### Project Structure
 
 ```
@@ -222,18 +219,22 @@ voicebox/
 
 ## Contributing
 
-Contributions welcome! Whether it's bug fixes, new features, or documentation improvements.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 1. Fork the repo
 2. Create a feature branch
 3. Make your changes
 4. Submit a PR
 
+## Security
+
+Found a security vulnerability? Please report it responsibly. See [SECURITY.md](SECURITY.md) for details.
+
 ---
 
 ## License
 
-MIT License — use it however you want.
+MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..bdf1e917
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,92 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Which versions are eligible for receiving such patches depends on the CVSS v3.0 Rating:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email security details to: [security@voicebox.sh](mailto:security@voicebox.sh)
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+We will:
+- Acknowledge receipt within 48 hours
+- Provide a timeline for addressing the issue
+- Keep you informed of progress
+- Credit you in the security advisory (if desired)
+
+## Security Best Practices
+
+### For Users
+
+- **Keep Voicebox updated** - Updates include security patches
+- **Verify downloads** - Only download from official releases
+- **Local processing** - Voice data stays on your machine
+- **Network security** - Use HTTPS when connecting to remote servers
+
+### For Developers
+
+- **Dependencies** - Keep all dependencies up to date
+- **Code review** - All PRs require review before merging
+- **Secrets** - Never commit API keys or signing keys
+- **Signing** - All releases are cryptographically signed
+
+## Known Security Considerations
+
+### Local Processing
+
+Voicebox processes all audio locally by default. Your voice data never leaves your machine unless you explicitly enable remote server mode.
+
+### Remote Server Mode
+
+When connecting to a remote server:
+- Ensure the server is on a trusted network
+- Use HTTPS for remote connections
+- Verify server identity before connecting
+
+### Auto-Updates
+
+- Updates are cryptographically signed
+- Signature verification happens before installation
+- Only HTTPS endpoints are allowed
+
+### Python Server
+
+The embedded Python server:
+- Runs locally by default (localhost only)
+- Can be configured for remote access
+- Uses standard FastAPI security practices
+
+## Disclosure Timeline
+
+- **Day 0**: Vulnerability reported
+- **Day 1-2**: Initial assessment and acknowledgment
+- **Day 3-7**: Investigation and fix development
+- **Day 8-14**: Testing and release preparation
+- **Day 15+**: Public disclosure (if applicable)
+
+Timeline may vary based on severity and complexity.
+
+## Security Updates
+
+Security updates will be:
+- Released as patch versions (e.g., 0.1.1)
+- Documented in CHANGELOG.md
+- Announced via GitHub releases
+- Automatically delivered via auto-updater
+
+---
+
+Thank you for helping keep Voicebox secure! 🔒
diff --git a/SETUP.md b/SETUP.md
index b99b6580..5bc265ab 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -1,6 +1,6 @@
-# voicebox Setup Guide
+# Development Setup Guide
 
-Quick start guide for setting up the voicebox development environment.
+This guide will help you set up the Voicebox development environment.
 
 ## Prerequisites
 
@@ -174,20 +174,23 @@ voicebox/
 
 ## Troubleshooting
 
-### Backend won't start
+See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues and solutions.
+
+### Quick Fixes
+
+**Backend won't start:**
 - Check Python version: `python --version` (needs 3.11+)
 - Ensure virtual environment is activated
 - Install dependencies: `pip install -r requirements.txt`
 
-### Tauri build fails
+**Tauri build fails:**
 - Ensure Rust is installed: `rustc --version`
 - Install Tauri CLI: `bunx @tauri-apps/cli install`
-- Check `tauri/src-tauri/Cargo.toml` for correct dependencies
+- Clean build: `cd tauri/src-tauri && cargo clean`
 
-### OpenAPI client generation fails
+**OpenAPI client generation fails:**
 - Ensure backend is running on port 8000
 - Check `curl http://localhost:8000/openapi.json` returns valid JSON
-- Install openapi-typescript-codegen: `bun add -d openapi-typescript-codegen`
 
 ## Model Downloads
 
@@ -199,9 +202,13 @@ First-time usage will be slower due to model downloads, but subsequent runs will
 
 ## Next Steps
 
-1. ✅ TTS model loading implemented in `backend/tts.py`
-2. ✅ API routes implemented in `backend/main.py`
-3. Build React components in `app/src/components/`
-4. Connect frontend to backend via generated API client
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
+- Check [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) if you encounter issues
+- Review [backend/README.md](backend/README.md) for API documentation
+- See [README.md](README.md) for project overview
 
-See [README.md](./README.md) for architecture details and [docs/](./docs/) for detailed documentation.
+## Additional Resources
+
+- [Auto-Updater Setup](docs/AUTOUPDATER_QUICKSTART.md) - Configure automatic updates
+- [Security Policy](SECURITY.md) - Security reporting and best practices
+- [Changelog](CHANGELOG.md) - Version history and changes
diff --git a/docs/ANALYSIS.md b/docs/ANALYSIS.md
deleted file mode 100644
index da3cac90..00000000
--- a/docs/ANALYSIS.md
+++ /dev/null
@@ -1,1215 +0,0 @@
-# Qwen3-TTS Implementation Analysis
-
-Comprehensive analysis of five existing Qwen3-TTS implementations to inform the architecture of voicebox.
-
----
-
-## Projects Analyzed
-
-1. **voice** - Rust CLI with Python backend
-2. **Voice-Clone-Studio** - Feature-rich Gradio app
-3. **Qwen3-TTS_server** - FastAPI REST API wrapper
-4. **mimic** - Web app with audio studio (conceptually the best)
-5. **qwen3-tts-enhanced** - Production-quality single-file Gradio app
-
----
-
-## 1. voice (Rust CLI)
-
-**Repository:** `/Users/jamespine/Projects/voice`
-
-### Architecture
-
-**Dual-mode design:**
-- One-shot mode: Single generation via CLI args
-- Server mode: Long-running HTTP server (port 3000)
-
-**Language split:**
-- Rust: CLI, HTTP server, IPC orchestration
-- Python: TTS inference, model management
-
-**IPC Pattern:**
-```
-Rust → spawn Python subprocess → JSON over stdin/stdout → Rust
-```
-
-### Python Backend (`tts.py`)
-
-**Model Management:**
-- Lazy loading via `get_tts_model()`
-- Qwen3-TTS CustomVoice models (0.6B/1.7B)
-- `torch_dtype=torch.bfloat16` for VRAM efficiency
-- Flash Attention 2 with SDPA fallback
-
-**Voice Profile System:**
-- Profiles stored in `~/.config/voice/profiles/`
-- Each profile: `audio.wav` + `reference.txt`
-- Automatic voice prompt creation and caching
-- Hash-based cache invalidation (MD5 of audio + text)
-
-**Generation Pipeline:**
-```python
-1. Load model (lazy, cached)
-2. Get voice prompt (cached if available)
-3. Set seed for reproducibility
-4. model.generate_voice_clone(text, language, voice_prompt)
-5. Save to temp file
-6. Return path as JSON
-```
-
-**Special Features:**
-- M3GAN voice effect (pitch shift + formant preservation)
-- Uses `librosa` + `soundfile` for audio processing
-- Voice profile listing with metadata
-
-### Rust Frontend
-
-**HTTP Server (`main.rs`):**
-- Axum web framework
-- Single endpoint: `POST /generate`
-- JSON request/response
-- Spawns Python subprocess per request
-
-**CLI (`cli.rs`):**
-- Clap for argument parsing
-- Commands: `generate`, `server`, `list-voices`
-- Profile management integrated
-
-**Process Management:**
-```rust
-let mut child = Command::new("python3")
-    .arg("tts.py")
-    .stdin(Stdio::piped())
-    .stdout(Stdio::piped())
-    .spawn()?;
-```
-
-### Strengths
-
-1. **Clean separation of concerns** - Rust for I/O, Python for ML
-2. **Dual-mode flexibility** - CLI and server in one binary
-3. **Voice profile abstraction** - Easy to add/manage voices
-4. **M3GAN effect** - Unique feature, well-implemented
-5. **Good error handling** - Rust's `Result` type enforced
-
-### Weaknesses
-
-1. **Synchronous inference** - Blocks during generation
-2. **No concurrent requests** - Server spawns subprocess per request
-3. **Limited caching** - Only voice prompts, not models
-4. **No generation history** - Fire and forget
-5. **Basic HTTP API** - No auth, rate limiting, or WebSocket streaming
-
-### Key Learnings
-
-- IPC via JSON stdin/stdout is simple and works
-- Voice profile pattern is user-friendly
-- For Tauri, we can skip the IPC layer and use direct HTTP/IPC channels
-- M3GAN effect is a differentiator worth preserving
-
----
-
-## 2. Voice-Clone-Studio
-
-**Repository:** `/Users/jamespine/Projects/Voice-Clone-Studio`
-
-### Architecture
-
-**Monolithic Gradio App:**
-- Single file: `voice_clone_studio.py` (2,815 lines)
-- Gradio for web UI
-- Global state for model management
-- Tab-based organization (6 tabs)
-
-### Model Support
-
-**Dual Engine:**
-1. **Qwen3-TTS** - Base, CustomVoice, VoiceDesign
-2. **VibeVoice TTS** - 1.5B/Large, multi-speaker
-
-**Model sizes:**
-- Qwen Small: 0.6B (~1GB VRAM)
-- Qwen Large: 1.7B (~3GB VRAM)
-- VibeVoice Small: 1.5B (~3GB VRAM)
-- VibeVoice Large: ~6GB VRAM
-- VibeVoice ASR: 7B (~14GB VRAM)
-
-### Voice Prompt Caching
-
-**Smart caching system:**
-```python
-def get_or_create_voice_prompt(audio_path, reference_text):
-    cache_key = hashlib.md5(audio_bytes + text.encode()).hexdigest()
-
-    # Check in-memory cache
-    if cache_key in _voice_prompt_cache:
-        return _voice_prompt_cache[cache_key]
-
-    # Check disk cache
-    prompt_file = f"{audio_path}.{cache_key}.prompt"
-    if os.path.exists(prompt_file):
-        prompt = torch.load(prompt_file)
-        _voice_prompt_cache[cache_key] = prompt
-        return prompt
-
-    # Create new
-    prompt = model.create_voice_clone_prompt(audio, text)
-    torch.save(prompt, prompt_file)
-    _voice_prompt_cache[cache_key] = prompt
-    return prompt
-```
-
-**Cache invalidation:**
-- Hash changes if audio or text changes
-- Orphaned `.prompt` files cleaned up on demand
-
-### Features
-
-**Tab 1: Voice Clone**
-- Clone from samples with Qwen or VibeVoice
-- Sample selection dropdown
-- Language selection (en/zh)
-- Seed control for reproducibility
-- Model size selection
-
-**Tab 2: Conversation**
-- Multi-speaker dialogue generation
-- Script format: `[1]: Text`, `[2]: Text`
-- Automatic speaker assignment
-- Pause duration control between speakers
-
-**Tab 3: Voice Presets**
-- 9 pre-built Qwen speakers
-- Style control (narrative, conversational, etc.)
-- No sample needed
-
-**Tab 4: Voice Design**
-- Generate voices from text descriptions
-- "Young female, energetic, bright tone"
-- Qwen VoiceDesign model (1.7B only)
-
-**Tab 5: Prep Samples**
-- Audio/video file upload
-- Auto-transcription (Whisper or VibeVoice ASR)
-- Audio editing (trim, normalize, mono conversion)
-- Save as voice sample
-
-**Tab 6: Output History**
-- Browse generated files
-- Metadata display (timestamp, seed, engine, text)
-- Re-generate from metadata
-
-### VRAM Management
-
-**Lazy loading + mutual exclusion:**
-```python
-def get_tts_model():
-    global _tts_model, _whisper_model, _vibe_voice_model
-
-    # Unload ASR to free VRAM
-    if _whisper_model:
-        del _whisper_model
-        _whisper_model = None
-    if _vibe_voice_model:
-        del _vibe_voice_model
-        _vibe_voice_model = None
-
-    torch.cuda.empty_cache()
-
-    if not _tts_model:
-        _tts_model = load_model(...)
-
-    return _tts_model
-```
-
-### Audio Processing
-
-**Pipeline:**
-1. **Input normalization:**
-   - Peak normalization to [-1, 1]
-   - 0.85 scaling (15% headroom)
-   - Stereo → mono (average channels)
-
-2. **Video extraction:**
-   - ffmpeg subprocess for audio extraction
-   - 24kHz mono output
-
-3. **Transcription:**
-   - Whisper medium model
-   - VibeVoice ASR with speaker diarization
-   - Auto-cleans `[Speaker X]:` labels
-
-4. **Generation:**
-   - Seed control via `torch.manual_seed()`
-   - bfloat16 inference
-   - Direct .wav output (soundfile)
-
-### Strengths
-
-1. **Voice prompt caching** - Brilliant UX (⚡ cached indicator)
-2. **Dual engine support** - Qwen + VibeVoice flexibility
-3. **Feature-rich** - Voice design, presets, conversations, long-form
-4. **VRAM efficiency** - Smart loading/unloading
-5. **Video support** - Extract audio from video files
-6. **Metadata tracking** - Every output has reproducibility data
-7. **Sample management** - Integrated prep workspace
-
-### Weaknesses
-
-1. **2,815-line single file** - Impossible to maintain
-2. **Global state everywhere** - Testing nightmare
-3. **Duplicated code** - 5 model loaders with identical fallback logic
-4. **No separation of concerns** - UI + logic + audio all mixed
-5. **No concurrency** - All operations block UI
-6. **No error recovery** - Generic error messages
-7. **Hardcoded parameters** - CFG scale, inference steps in function bodies
-8. **No tests** - Zero test coverage
-9. **No logging** - Only print statements
-
-### Key Learnings
-
-**Adopt:**
-- Voice prompt caching with hash validation
-- Lazy model loading with automatic unloading
-- Metadata alongside outputs
-- Sample management patterns
-- Status indicators (cached vs not)
-
-**Avoid:**
-- Monolithic files over 2,000 lines
-- Global mutable state
-- Duplicated logic without abstraction
-- Hardcoded parameters
-
----
-
-## 3. Qwen3-TTS_server
-
-**Repository:** `/Users/jamespine/Projects/Qwen3-TTS_server`
-
-### Architecture
-
-**FastAPI REST API:**
-- Single server process
-- Three endpoints: `/generate`, `/clone`, `/health`
-- Deployed on RunPod with Docker
-- Port 8000 (configurable)
-
-### Project Structure
-
-```
-Qwen3-TTS_server/
-├── main.py              # FastAPI app
-├── models/
-│   └── tts.py          # Model management
-├── api/
-│   └── routes.py       # Endpoint definitions
-├── utils/
-│   └── audio.py        # Audio processing
-├── config.py           # Settings
-├── Dockerfile          # Multi-stage build
-└── requirements.txt    # Dependencies
-```
-
-### API Design
-
-**POST /generate**
-```json
-{
-  "text": "Hello world",
-  "language": "en",
-  "speaker": "default",
-  "seed": 42
-}
-
-Response:
-{
-  "audio_url": "https://...",
-  "duration": 2.5,
-  "sample_rate": 24000
-}
-```
-
-**POST /clone**
-```json
-{
-  "text": "Hello world",
-  "language": "en",
-  "reference_audio": "base64_encoded_audio",
-  "reference_text": "This is my voice",
-  "seed": 42
-}
-
-Response:
-{
-  "audio_url": "https://...",
-  "duration": 2.5,
-  "sample_rate": 24000
-}
-```
-
-**GET /health**
-```json
-{
-  "status": "healthy",
-  "model_loaded": true,
-  "gpu_available": true,
-  "vram_used_mb": 1024
-}
-```
-
-### Model Management
-
-**Singleton pattern:**
-```python
-class ModelManager:
-    _instance = None
-    _model = None
-
-    def __new__(cls):
-        if not cls._instance:
-            cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def get_model(self):
-        if not self._model:
-            self._model = self._load_model()
-        return self._model
-```
-
-**Lazy loading:**
-- Model loaded on first request
-- Kept in memory for subsequent requests
-- No unloading (server dedicated to TTS)
-
-### Deployment
-
-**Docker multi-stage build:**
-```dockerfile
-FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 AS base
-# Install dependencies
-
-FROM base AS builder
-# Install Python packages
-
-FROM base AS runtime
-COPY --from=builder /usr/local/lib/python3.10 /usr/local/lib/python3.10
-# Runtime only
-```
-
-**RunPod integration:**
-- Configured for GPU instances
-- Automatic model download on startup
-- Health checks for orchestration
-
-### Strengths
-
-1. **Clean API design** - RESTful, well-documented
-2. **Proper separation** - Routes, models, utils in separate modules
-3. **Singleton model manager** - Better than global variables
-4. **Health endpoint** - Essential for deployment
-5. **Docker deployment** - Production-ready containerization
-6. **Base64 audio input** - No file upload needed for cloning
-
-### Weaknesses
-
-1. **No authentication** - Wide open API
-2. **No rate limiting** - DoS vulnerable
-3. **Sequential inference** - No request queuing
-4. **No caching** - Voice prompts recreated every time
-5. **No streaming** - Returns only after full generation
-6. **No WebSocket** - Can't send progress updates
-7. **Synchronous endpoints** - Blocks during generation
-8. **No storage** - Audio URLs expire quickly
-9. **Limited error handling** - Generic 500 errors
-
-### Key Learnings
-
-**Adopt:**
-- FastAPI for REST API
-- Modular structure (routes, models, utils)
-- Health endpoint for monitoring
-- Base64 audio input option
-- Docker deployment pattern
-
-**Improve:**
-- Add async/await throughout
-- Implement request queue
-- Add WebSocket for streaming
-- Cache voice prompts
-- Authentication and rate limiting
-
----
-
-## 4. mimic
-
-**Repository:** `/Users/jamespine/Projects/mimic`
-
-### Architecture
-
-**Three-tier web app:**
-- Frontend: Vanilla JS (no framework)
-- Backend: Python FastAPI
-- Database: SQLite
-
-**Best-structured backend** of all projects analyzed.
-
-### Project Structure
-
-```
-mimic/
-├── backend/
-│   ├── main.py              # FastAPI app
-│   ├── models.py            # Pydantic models
-│   ├── tts.py              # TTS inference
-│   ├── transcribe.py       # Whisper ASR
-│   ├── profiles.py         # Voice profile management
-│   ├── history.py          # Generation history
-│   ├── studio.py           # Audio studio features
-│   └── database.py         # SQLite ORM
-├── frontend/
-│   ├── index.html
-│   ├── app.js              # Main app (2,794 lines)
-│   ├── studio.js           # Audio studio (2,363 lines)
-│   ├── profiles.js         # Profile management
-│   └── history.js          # History UI
-└── data/
-    ├── profiles/           # Voice profiles
-    ├── generations/        # Generated audio
-    └── mimic.db           # SQLite database
-```
-
-### Backend Design
-
-**Async/await throughout:**
-```python
-@router.post("/generate")
-async def generate(request: GenerateRequest):
-    audio = await tts.generate_async(
-        text=request.text,
-        profile_id=request.profile_id,
-        language=request.language
-    )
-
-    history_entry = await db.create_generation(
-        profile_id=request.profile_id,
-        text=request.text,
-        audio_path=audio.path
-    )
-
-    return history_entry
-```
-
-**Modular separation:**
-- `models.py` - Pydantic request/response models
-- `tts.py` - TTS inference logic only
-- `transcribe.py` - ASR logic only
-- `profiles.py` - CRUD for voice profiles
-- `history.py` - CRUD for generation history
-- `studio.py` - Audio editing features
-- `database.py` - SQLAlchemy ORM
-
-### Features
-
-**Voice Profiles:**
-- Create from audio file + reference text
-- Multiple samples per profile (combined)
-- Metadata: name, description, tags, language
-- Thumbnail generation from waveform
-
-**Generation History:**
-- SQLite database with full-text search
-- Filters: profile, date range, language
-- Regeneration from history
-- Export to various formats
-
-**Audio Studio:**
-- Timeline-based editing
-- Multiple audio tracks
-- Word-level timestamps (Whisper alignment)
-- Trim, fade, volume control
-- Export with normalization
-
-**Projects:**
-- Save/load studio sessions
-- Project metadata and versioning
-- Export project as single file
-
-### Database Schema
-
-```sql
-CREATE TABLE profiles (
-    id INTEGER PRIMARY KEY,
-    name TEXT UNIQUE,
-    description TEXT,
-    language TEXT,
-    created_at TIMESTAMP,
-    updated_at TIMESTAMP
-);
-
-CREATE TABLE profile_samples (
-    id INTEGER PRIMARY KEY,
-    profile_id INTEGER,
-    audio_path TEXT,
-    reference_text TEXT,
-    FOREIGN KEY (profile_id) REFERENCES profiles(id)
-);
-
-CREATE TABLE generations (
-    id INTEGER PRIMARY KEY,
-    profile_id INTEGER,
-    text TEXT,
-    language TEXT,
-    audio_path TEXT,
-    duration REAL,
-    seed INTEGER,
-    created_at TIMESTAMP,
-    FOREIGN KEY (profile_id) REFERENCES profiles(id)
-);
-
-CREATE TABLE projects (
-    id INTEGER PRIMARY KEY,
-    name TEXT,
-    data JSON,
-    created_at TIMESTAMP,
-    updated_at TIMESTAMP
-);
-```
-
-### Frontend Design
-
-**Major issue: Monolithic classes**
-
-**app.js (2,794 lines):**
-```javascript
-class MimicApp {
-    constructor() {
-        this.profiles = [];
-        this.generations = [];
-        this.currentProfile = null;
-        this.currentGeneration = null;
-        // ... 50+ properties
-    }
-
-    // 80+ methods, no organization
-    async loadProfiles() { ... }
-    async createProfile() { ... }
-    async deleteProfile() { ... }
-    async generate() { ... }
-    async loadHistory() { ... }
-    // ... hundreds more lines
-}
-```
-
-**studio.js (2,363 lines):**
-```javascript
-class AudioStudio {
-    constructor() {
-        this.wavesurfer = null;
-        this.timeline = null;
-        this.tracks = [];
-        this.regions = [];
-        this.words = [];
-        // ... 40+ properties
-    }
-
-    // 60+ methods, all mixed
-    initWavesurfer() { ... }
-    addTrack() { ... }
-    removeTrack() { ... }
-    playPause() { ... }
-    exportAudio() { ... }
-    // ... hundreds more lines
-}
-```
-
-**Global state everywhere:**
-```javascript
-let app = null;
-let studio = null;
-let currentProfile = null;
-let isGenerating = false;
-```
-
-**No module system:**
-- All files loaded via `<script>` tags
-- No bundler, no tree-shaking
-- jQuery for DOM manipulation
-- No type safety
-
-### Audio Studio Implementation
-
-**WaveSurfer.js integration:**
-```javascript
-this.wavesurfer = WaveSurfer.create({
-    container: '#waveform',
-    waveColor: '#4a9eff',
-    progressColor: '#1e3a8a',
-    cursorColor: '#ef4444',
-    height: 128,
-    normalize: true,
-    plugins: [
-        TimelinePlugin.create(),
-        RegionsPlugin.create()
-    ]
-});
-```
-
-**Word-level timestamps:**
-- Whisper alignment API
-- Each word: `{ word, start, end }`
-- Clickable timeline
-- Visual highlighting during playback
-
-**Track mixing:**
-- Multiple audio files on timeline
-- Independent volume control
-- Fade in/out per track
-- Export as single mixed audio
-
-### Strengths
-
-1. **Best backend structure** - Modular, async, clean separation
-2. **Database-backed** - Proper persistence layer
-3. **Audio studio** - Timeline editing is unique
-4. **Word-level timestamps** - Great UX for editing
-5. **Project system** - Save/load sessions
-6. **Search and filters** - Full-text search in history
-7. **Multi-sample profiles** - Combine multiple references
-8. **Proper API design** - RESTful with Pydantic validation
-
-### Weaknesses
-
-1. **Frontend is amateur:**
-   - 2,794-line app.js
-   - 2,363-line studio.js
-   - Global state everywhere
-   - No module system
-   - No TypeScript
-   - jQuery instead of modern framework
-
-2. **No real-time updates** - Polling instead of WebSocket
-3. **No concurrency** - Single generation at a time
-4. **No batch processing** - One at a time only
-5. **Limited audio formats** - WAV only
-6. **No export options** - Can't export profiles or projects easily
-
-### Key Learnings
-
-**Backend patterns to adopt:**
-- Async/await throughout
-- Modular file structure (tts.py, transcribe.py, profiles.py, history.py)
-- SQLite for persistence
-- Pydantic for validation
-- Proper CRUD separation
-
-**Frontend patterns to avoid:**
-- Monolithic classes over 2,000 lines
-- Global state
-- jQuery-based architecture
-- No type safety
-
-**Features to adopt:**
-- Audio studio with timeline
-- Word-level timestamps
-- Project system
-- Multi-sample voice profiles
-- Generation history with search
-
----
-
-## 5. qwen3-tts-enhanced
-
-**Repository:** `/Users/jamespine/Projects/qwen3-tts-enhanced`
-
-### Architecture
-
-**Production-quality Gradio app:**
-- Single file: `app.py` (1,892 lines)
-- Much cleaner than Voice-Clone-Studio despite being monolithic
-- Clear section comments and function organization
-- Cross-platform support (Windows, Mac, Linux)
-
-### Unique Features
-
-**Multi-Reference Voice Cloning:**
-```python
-def combine_references(audio_paths, reference_texts):
-    """Combine multiple voice samples for better quality"""
-    combined_audio = []
-    combined_text = []
-
-    for audio_path, text in zip(audio_paths, reference_texts):
-        audio, sr = sf.read(audio_path)
-        audio = normalize_audio(audio)
-        combined_audio.append(audio)
-        combined_text.append(text)
-
-    # Mix with equal weighting and normalization
-    mixed = np.concatenate(combined_audio)
-    mixed = normalize_audio(mixed)
-
-    combined_text_str = " ".join(combined_text)
-
-    return mixed, combined_text_str
-```
-
-**Batch Variation Generation:**
-- Generate N variations of same text
-- Different seeds for each
-- Compare and pick best output
-- Parallel generation support
-
-**Smart Audio Mixing:**
-```python
-def normalize_audio(audio, target_db=-20):
-    """Normalize to target loudness with peak limiting"""
-    # Convert to float32
-    audio = audio.astype(np.float32)
-
-    # Calculate current RMS
-    rms = np.sqrt(np.mean(audio**2))
-
-    # Calculate target RMS
-    target_rms = 10**(target_db / 20)
-
-    # Apply gain
-    if rms > 0:
-        gain = target_rms / rms
-        audio = audio * gain
-
-    # Peak limiting to prevent clipping
-    audio = np.clip(audio, -1.0, 1.0)
-
-    return audio
-```
-
-### Code Organization
-
-**Clear sections:**
-```python
-# ============================================
-# CONFIGURATION AND CONSTANTS
-# ============================================
-
-# ============================================
-# MODEL MANAGEMENT
-# ============================================
-
-# ============================================
-# AUDIO PROCESSING
-# ============================================
-
-# ============================================
-# GENERATION FUNCTIONS
-# ============================================
-
-# ============================================
-# UI COMPONENTS
-# ============================================
-
-# ============================================
-# APPLICATION LAUNCH
-# ============================================
-```
-
-**Consistent patterns:**
-- All functions have docstrings
-- Type hints on critical functions
-- Error handling with context
-- Progress callbacks throughout
-
-### Cross-Platform Support
-
-**Graceful degradation:**
-```python
-def get_audio_device():
-    """Get audio playback device, cross-platform"""
-    try:
-        import sounddevice as sd
-        devices = sd.query_devices()
-        return sd.default.device
-    except ImportError:
-        logger.warning("sounddevice not available, using fallback")
-        return None
-    except Exception as e:
-        logger.warning(f"Audio device detection failed: {e}")
-        return None
-
-def play_audio(audio_path):
-    """Play audio with platform-specific fallback"""
-    device = get_audio_device()
-
-    if device is not None:
-        # Use sounddevice
-        audio, sr = sf.read(audio_path)
-        sd.play(audio, sr)
-    elif sys.platform == 'darwin':
-        # macOS fallback
-        subprocess.run(['afplay', audio_path])
-    elif sys.platform == 'win32':
-        # Windows fallback
-        import winsound
-        winsound.PlaySound(audio_path, winsound.SND_FILENAME)
-    else:
-        # Linux fallback
-        subprocess.run(['aplay', audio_path])
-```
-
-**Path handling:**
-```python
-def ensure_cross_platform_path(path):
-    """Convert paths to platform-specific format"""
-    return os.path.normpath(path)
-
-def get_config_dir():
-    """Get config directory, respecting platform conventions"""
-    if sys.platform == 'win32':
-        return os.path.join(os.getenv('APPDATA'), 'qwen-tts')
-    elif sys.platform == 'darwin':
-        return os.path.expanduser('~/Library/Application Support/qwen-tts')
-    else:
-        return os.path.expanduser('~/.config/qwen-tts')
-```
-
-### Quality Improvements
-
-**Reference audio validation:**
-```python
-def validate_reference_audio(audio_path):
-    """Check if reference audio is suitable for cloning"""
-    audio, sr = sf.read(audio_path)
-
-    # Check duration (3-10 seconds ideal)
-    duration = len(audio) / sr
-    if duration < 2:
-        return False, "Audio too short (minimum 2 seconds)"
-    if duration > 30:
-        return False, "Audio too long (maximum 30 seconds)"
-
-    # Check for silence
-    rms = np.sqrt(np.mean(audio**2))
-    if rms < 0.01:
-        return False, "Audio is too quiet or silent"
-
-    # Check for clipping
-    if np.abs(audio).max() > 0.99:
-        return False, "Audio is clipping (reduce input gain)"
-
-    # Check sample rate
-    if sr < 16000:
-        return False, f"Sample rate too low ({sr}Hz, minimum 16kHz)"
-
-    return True, "Audio is suitable"
-```
-
-**Generation quality settings:**
-```python
-# Conservative defaults for quality
-DEFAULT_CFG_SCALE = 4.5  # Higher = more faithful to prompt
-DEFAULT_STEPS = 20       # More steps = better quality
-DEFAULT_TEMPERATURE = 1.0
-
-# Fast mode (lower quality)
-FAST_CFG_SCALE = 3.0
-FAST_STEPS = 10
-```
-
-### Backward Compatibility
-
-**Config migration:**
-```python
-def migrate_config(config):
-    """Migrate old config to new format"""
-    version = config.get('version', 1)
-
-    if version == 1:
-        # Add new fields from version 2
-        config['batch_size'] = 1
-        config['version'] = 2
-
-    if version == 2:
-        # Add new fields from version 3
-        config['multi_reference'] = False
-        config['version'] = 3
-
-    return config
-```
-
-**Legacy sample format:**
-```python
-def load_sample(sample_path):
-    """Load voice sample, supporting both old and new formats"""
-    # Try new format (JSON metadata)
-    json_path = sample_path.replace('.wav', '.json')
-    if os.path.exists(json_path):
-        with open(json_path) as f:
-            metadata = json.load(f)
-        return {
-            'audio': sample_path,
-            'text': metadata['reference_text'],
-            'language': metadata.get('language', 'en')
-        }
-
-    # Try old format (text file)
-    txt_path = sample_path.replace('.wav', '.txt')
-    if os.path.exists(txt_path):
-        with open(txt_path) as f:
-            text = f.read().strip()
-        return {
-            'audio': sample_path,
-            'text': text,
-            'language': 'en'  # Assume English
-        }
-
-    # No metadata found
-    return None
-```
-
-### Strengths
-
-1. **Multi-reference cloning** - Combine samples for better quality
-2. **Batch variations** - Generate multiple outputs, pick best
-3. **Smart audio normalization** - RMS targeting + peak limiting
-4. **Cross-platform support** - Graceful degradation everywhere
-5. **Backward compatibility** - Config migration, legacy formats
-6. **Reference validation** - Check audio before generation
-7. **Quality presets** - Fast vs. high-quality modes
-8. **Clean code** - Well-organized despite being single file
-9. **Good error messages** - Contextual, actionable
-10. **Progress callbacks** - User sees what's happening
-
-### Weaknesses
-
-1. **Still monolithic** - 1,892 lines in one file
-2. **No database** - File-based storage
-3. **No history** - Can't search past generations
-4. **No API** - Gradio UI only
-5. **No concurrent generation** - One at a time
-6. **No streaming** - Wait for full generation
-
-### Key Learnings
-
-**Production patterns to adopt:**
-- Multi-reference combination for quality
-- Audio validation before generation
-- Cross-platform graceful degradation
-- Config migration for backward compatibility
-- RMS normalization with peak limiting
-- Quality presets (fast vs. high-quality)
-- Clear section organization in code
-- Progress callbacks everywhere
-
-**Clean code practices:**
-- Docstrings on all functions
-- Type hints where useful
-- Error messages with context
-- Consistent naming conventions
-
----
-
-## Comparative Analysis
-
-### Model Management
-
-| Project | Pattern | VRAM Strategy | Caching |
-|---------|---------|--------------|---------|
-| voice | Lazy load | Single model | Voice prompts only |
-| Voice-Clone-Studio | Lazy + mutex | Unload on switch | Voice prompts + disk |
-| Qwen3-TTS_server | Singleton | Keep in memory | None |
-| mimic | Lazy async | Single model | None |
-| qwen3-tts-enhanced | Lazy load | Single model | Voice prompts only |
-
-**Winner:** Voice-Clone-Studio (most sophisticated caching)
-
-### Architecture
-
-| Project | Backend | Frontend | Separation | Modularity |
-|---------|---------|----------|------------|------------|
-| voice | Python subprocess | Rust CLI | Excellent | Good |
-| Voice-Clone-Studio | Gradio monolith | Gradio | None | Poor |
-| Qwen3-TTS_server | FastAPI | None (API only) | Excellent | Excellent |
-| mimic | FastAPI | Vanilla JS | Good | Backend: Excellent, Frontend: Poor |
-| qwen3-tts-enhanced | Gradio monolith | Gradio | None | Good (sections) |
-
-**Winner:** mimic (backend), Qwen3-TTS_server (overall separation)
-
-### Features
-
-| Feature | voice | Voice-Clone-Studio | Qwen3-TTS_server | mimic | qwen3-tts-enhanced |
-|---------|-------|-------------------|-----------------|-------|-------------------|
-| Voice cloning | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Multi-reference | ✗ | ✗ | ✗ | ✓ | ✓ |
-| Voice design | ✗ | ✓ | ✗ | ✗ | ✗ |
-| Presets | ✗ | ✓ (9) | ✗ | ✗ | ✗ |
-| Conversations | ✗ | ✓ | ✗ | ✗ | ✗ |
-| History | ✗ | ✓ (file) | ✗ | ✓ (database) | ✗ |
-| Audio studio | ✗ | ✗ | ✗ | ✓ | ✗ |
-| Batch generation | ✗ | ✗ | ✗ | ✗ | ✓ |
-| M3GAN effect | ✓ | ✗ | ✗ | ✗ | ✗ |
-
-**Winner:** mimic (most comprehensive feature set)
-
-### Code Quality
-
-| Project | Lines | Organization | Type Safety | Tests | Documentation |
-|---------|-------|--------------|-------------|-------|---------------|
-| voice | ~500 | Good | Rust: Yes, Python: No | None | README only |
-| Voice-Clone-Studio | 2,815 | Poor | No | None | Good README |
-| Qwen3-TTS_server | ~800 | Excellent | Partial (Pydantic) | None | API docs |
-| mimic | ~4,000 | Backend: Good, Frontend: Poor | Backend: Partial | None | Basic |
-| qwen3-tts-enhanced | 1,892 | Good | Partial | None | Good |
-
-**Winner:** Qwen3-TTS_server (best organized)
-
-### Production Readiness
-
-| Project | Deployment | Error Handling | Cross-Platform | Graceful Degradation | Monitoring |
-|---------|-----------|----------------|----------------|---------------------|------------|
-| voice | Binary | Good (Rust) | Yes | Limited | None |
-| Voice-Clone-Studio | Python script | Basic | Yes | Good (flash attn) | None |
-| Qwen3-TTS_server | Docker | Basic | Linux (container) | None | Health endpoint |
-| mimic | Python script | Good | Yes | Limited | None |
-| qwen3-tts-enhanced | Python script | Excellent | Excellent | Excellent | None |
-
-**Winner:** qwen3-tts-enhanced (most robust), Qwen3-TTS_server (deployment)
-
----
-
-## Recommended Architecture for voicebox
-
-### Backend (Python + FastAPI)
-
-**Structure (from mimic):**
-```
-backend/
-├── main.py              # FastAPI app
-├── models.py            # Pydantic models
-├── tts.py              # TTS inference
-├── transcribe.py       # Whisper ASR
-├── profiles.py         # Voice profile management
-├── history.py          # Generation history
-├── studio.py           # Audio editing
-├── effects.py          # M3GAN, etc.
-├── database.py         # SQLite ORM
-└── utils/
-    ├── audio.py        # Audio processing
-    ├── cache.py        # Voice prompt caching
-    └── validation.py   # Input validation
-```
-
-**Patterns to adopt:**
-- Async/await throughout (mimic)
-- Voice prompt caching (Voice-Clone-Studio)
-- Multi-reference combination (qwen3-tts-enhanced)
-- Audio validation (qwen3-tts-enhanced)
-- Cross-platform audio (qwen3-tts-enhanced)
-- Health endpoint (Qwen3-TTS_server)
-- Graceful degradation (qwen3-tts-enhanced)
-
-### Frontend (Tauri + TypeScript + React)
-
-**Structure:**
-```
-frontend/
-├── src/
-│   ├── components/
-│   │   ├── VoiceProfiles/
-│   │   ├── Generation/
-│   │   ├── AudioStudio/
-│   │   └── History/
-│   ├── lib/
-│   │   ├── api.ts          # Backend API client
-│   │   ├── audio.ts        # Audio utilities
-│   │   └── store.ts        # State management
-│   ├── types/
-│   │   └── index.ts        # TypeScript types
-│   └── App.tsx
-└── src-tauri/
-    ├── src/
-    │   └── main.rs         # Tauri backend
-    └── tauri.conf.json
-```
-
-**Avoid monolithic components:**
-- Keep components under 300 lines
-- Proper state management (Zustand or Jotai)
-- TypeScript everywhere
-- Component-based architecture
-
-### Features Priority
-
-**Phase 1 (MVP):**
-1. Voice profile management
-2. Single-reference voice cloning
-3. Generation history (database)
-4. Basic audio playback
-
-**Phase 2:**
-1. Multi-reference combination
-2. Batch variation generation
-3. M3GAN effect
-4. Audio normalization
-
-**Phase 3:**
-1. Audio studio with timeline
-2. Word-level timestamps
-3. Project system
-4. Export options
-
-**Phase 4:**
-1. Voice design
-2. Preset voices
-3. Conversation mode
-4. Advanced effects
-
-### Technology Stack
-
-**Backend:**
-- FastAPI (async REST API)
-- SQLAlchemy (database ORM)
-- Pydantic (validation)
-- Qwen3-TTS (model)
-- Whisper (transcription)
-- librosa + soundfile (audio)
-
-**Frontend:**
-- Tauri (desktop framework)
-- React (UI framework)
-- TypeScript (type safety)
-- Tailwind CSS (styling)
-- Zustand (state management)
-- WaveSurfer.js (audio visualization)
-
-**Database:**
-- SQLite (local storage)
-- Alembic (migrations)
-
-### Key Differentiators
-
-What will make voicebox better:
-
-1. **Clean architecture** - Avoid monolithic files from all projects
-2. **TypeScript frontend** - Type safety unlike mimic
-3. **Desktop-first** - Native feel via Tauri
-4. **Voice prompt caching** - Fast generations like Voice-Clone-Studio
-5. **Multi-reference** - Quality like qwen3-tts-enhanced
-6. **Audio studio** - Timeline editing like mimic
-7. **M3GAN effect** - Unique feature from voice
-8. **Production code** - No amateur patterns
-9. **Proper state management** - No global variables
-10. **Modular from day one** - Easy to extend
-
----
-
-## Conclusion
-
-All five projects have valuable lessons:
-
-- **voice**: Clean Rust/Python split, M3GAN effect
-- **Voice-Clone-Studio**: Brilliant caching, feature-rich but poorly organized
-- **Qwen3-TTS_server**: Best modular structure, API design
-- **mimic**: Best backend architecture, great features, terrible frontend
-- **qwen3-tts-enhanced**: Production patterns, quality focus, cross-platform
-
-voicebox will cherry-pick the best patterns from each while avoiding their architectural mistakes.
diff --git a/docs/AUTOUPDATER.md b/docs/AUTOUPDATER.md
index 621d01eb..06de6002 100644
--- a/docs/AUTOUPDATER.md
+++ b/docs/AUTOUPDATER.md
@@ -1,6 +1,6 @@
-# Tauri v2 Autoupdater Setup
+# Auto-Updater Documentation
 
-The autoupdater has been configured for this project. Follow these steps to complete the setup.
+Voicebox includes automatic updates powered by Tauri's updater plugin. This document explains how it works for both users and developers.
 
 ## 1. Generate Signing Keys
 
@@ -148,28 +148,15 @@ Add your private key to GitHub secrets:
 - Add `TAURI_SIGNING_PRIVATE_KEY` with the content of `~/.tauri/voicebox.key`
 - Add `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` (empty string if no password)
 
-## 5. Frontend Integration (Already Completed)
+## Frontend Integration
 
-The frontend integration is already complete in this project with the following components:
+The frontend integration is complete with automatic update notifications and manual update checks:
 
-### Automatic Update Notifications
-- `app/src/components/UpdateNotification.tsx` - Shows a banner when updates are available
-- Automatically checks for updates on app startup
-- Displays download/install progress
-- Only shows in Tauri desktop builds
+- **Update Notification Banner** - Appears automatically when updates are available
+- **Settings Panel** - Manual "Check for Updates" button in Settings tab
+- **Update Hook** - React hook handles all update operations
 
-### Manual Update Check
-- `app/src/components/ServerSettings/UpdateStatus.tsx` - Settings panel for updates
-- Allows manual update checks via "Check for Updates" button
-- Shows current version and update status
-- Located in the Settings tab (only visible in Tauri builds)
-
-### Update Hook
-- `app/src/hooks/useAutoUpdater.ts` - React hook for update functionality
-- Handles update checking, downloading, and installation
-- Includes Tauri context detection (won't run in web builds)
-
-The components are already integrated into the main App layout.
+See `docs/AUTOUPDATER_QUICKSTART.md` for a quick setup guide.
 
 ## Security Notes
 
diff --git a/docs/BACKEND_COMPLETE.md b/docs/BACKEND_COMPLETE.md
deleted file mode 100644
index 8ec00905..00000000
--- a/docs/BACKEND_COMPLETE.md
+++ /dev/null
@@ -1,246 +0,0 @@
-# 🎉 Backend Implementation Complete!
-
-Your voicebox backend is fully implemented and ready for frontend integration.
-
-## What Was Built
-
-### 📦 Complete Backend (1,500 lines, 12 files)
-
-I've implemented a **production-quality FastAPI backend** based on the best patterns from your reference projects:
-
-#### Core Modules
-
-1. **TTS Module** (`backend/tts.py`)
-   - Qwen3-TTS model loading and inference
-   - Voice prompt creation with caching
-   - Multi-reference combination
-   - Model size switching (1.7B/0.6B)
-   - Async generation
-
-2. **Profiles Module** (`backend/profiles.py`)
-   - Full CRUD for voice profiles
-   - Multi-sample support per profile
-   - Audio validation
-   - Automatic sample combination
-
-3. **History Module** (`backend/history.py`)
-   - Generation tracking with full metadata
-   - Search and filtering
-   - Pagination
-   - Statistics
-
-4. **Transcription Module** (`backend/transcribe.py`)
-   - Whisper ASR integration
-   - Language hints
-   - Model management
-
-5. **Database Module** (`backend/database.py`)
-   - SQLite with SQLAlchemy ORM
-   - Clean schema design
-   - Proper relationships
-
-6. **Utils Module** (`backend/utils/`)
-   - Audio processing and validation
-   - Voice prompt caching (memory + disk)
-   - Input validation
-
-7. **API Module** (`backend/main.py`)
-   - 20+ REST endpoints
-   - File upload/download
-   - Health checks
-   - Model management
-
-## 🎯 What's Different from References
-
-### Better Than ALL References
-
-| Feature | Your Backend | Reference Projects |
-|---------|-------------|-------------------|
-| **Code Organization** | ✅ 12 modular files (~1,500 lines) | ❌ 1-2 monolithic files (2,815 lines) |
-| **Type Safety** | ✅ 100% Pydantic + type hints | ❌ Little to no typing |
-| **Async/Await** | ✅ Full async throughout | ⚠️ Partial or none |
-| **Caching** | ✅ Voice prompts (memory + disk) | ⚠️ Partial or none |
-| **Multi-Sample** | ✅ Advanced combination | ⚠️ Basic or none |
-| **Database** | ✅ SQLite with search | ❌ File-based |
-| **API Design** | ✅ 20+ RESTful endpoints | ⚠️ 3 endpoints or Gradio only |
-| **Error Handling** | ✅ Detailed + contextual | ⚠️ Generic |
-
-### Pattern Sources
-
-- ✅ **Architecture** from mimic (best structured)
-- ✅ **Caching** from Voice-Clone-Studio (brilliant implementation)
-- ✅ **Audio processing** from qwen3-tts-enhanced (quality focus)
-- ✅ **API design** from Qwen3-TTS_server (clean REST)
-- ✅ **Best practices** from professional software engineering
-
-### What We Avoided
-
-- ❌ No 2,815-line monolithic files
-- ❌ No global mutable state
-- ❌ No synchronous blocking
-- ❌ No code duplication
-- ❌ No poor separation of concerns
-
-## 📚 Documentation Created
-
-1. **`backend/README.md`** - Complete API documentation
-2. **`backend/IMPLEMENTATION_STATUS.md`** - Implementation status
-3. **`backend/example_usage.py`** - Working example client
-4. **`docs/BACKEND_IMPLEMENTATION.md`** - Implementation details
-5. **`docs/COMPETITIVE_ANALYSIS.md`** - Comparison with references
-
-## 🚀 Ready For
-
-### ✅ Immediate Integration
-
-The backend is ready for:
-- Tauri desktop app integration
-- Web app deployment  
-- OpenAPI client generation
-- Production deployment
-
-### 🔌 All Endpoints Working
-
-```
-Health:
-  GET  /health
-
-Profiles:
-  POST   /profiles
-  GET    /profiles
-  GET    /profiles/{id}
-  PUT    /profiles/{id}
-  DELETE /profiles/{id}
-  POST   /profiles/{id}/samples
-  GET    /profiles/{id}/samples
-  DELETE /profiles/samples/{id}
-
-Generation:
-  POST /generate
-
-History:
-  GET    /history
-  GET    /history/{id}
-  DELETE /history/{id}
-  GET    /history/stats
-
-Audio:
-  GET /audio/{id}
-
-Transcription:
-  POST /transcribe
-
-Models:
-  POST /models/load
-  POST /models/unload
-```
-
-## 🎬 Next Steps
-
-### 1. Test the Backend
-
-```bash
-# Terminal 1: Start backend
-cd backend
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-python main.py
-
-# Terminal 2: Test it
-curl http://localhost:8000/health
-python backend/example_usage.py
-```
-
-### 2. Generate OpenAPI Client
-
-```bash
-# Start backend first, then:
-curl http://localhost:8000/openapi.json > app/openapi.json
-
-cd app
-npx openapi-typescript-codegen \
-  --input openapi.json \
-  --output src/lib/api \
-  --client fetch
-```
-
-### 3. Build Frontend
-
-Now you can build the Tauri frontend that:
-- Creates voice profiles
-- Uploads audio samples  
-- Generates speech
-- Views history
-- Downloads audio
-
-## 📊 Performance
-
-- **First generation:** 6-10 seconds (creates prompt)
-- **Cached generation:** 1-2 seconds (uses cache)
-- **Model loading:** 3-5 seconds (one-time)
-- **Voice prompt cache:** Persists across restarts
-
-## 🎯 Key Benefits
-
-1. **Maintainable** - Clean, modular, documented
-2. **Type-safe** - Catch errors at development time
-3. **Fast** - Caching makes repeat generations instant
-4. **Complete** - All core features implemented
-5. **Professional** - Production-ready patterns throughout
-
-## 🔮 Future Enhancements (Optional)
-
-These are planned but not blocking frontend work:
-
-**Phase 2:**
-- WebSocket streaming for progress
-- Batch generation endpoint
-- Audio effects (M3GAN)
-- Voice design
-
-**Phase 3:**
-- Audio studio timeline
-- Word-level timestamps
-- Project management
-
-**Phase 4:**
-- Authentication
-- Rate limiting
-- Docker deployment
-- CI/CD
-
-## 📖 Reference Projects Analyzed
-
-Based on analysis of:
-- **voice** - Rust CLI with Python backend
-- **Voice-Clone-Studio** - Feature-rich Gradio app
-- **Qwen3-TTS_server** - Clean FastAPI wrapper
-- **mimic** - Web app with best backend structure
-- **qwen3-tts-enhanced** - Production-quality Gradio
-
-## ✨ Summary
-
-**Your backend is:**
-- ✅ Fully implemented (20+ endpoints)
-- ✅ Production-ready (error handling, health checks)
-- ✅ Well-documented (5 documentation files)
-- ✅ Type-safe (100% Pydantic)
-- ✅ Performant (voice prompt caching)
-- ✅ Maintainable (clean architecture)
-
-**Status:** READY FOR FRONTEND INTEGRATION
-
-**No blockers.** You can start building the Tauri app immediately!
-
----
-
-## Questions?
-
-See the documentation:
-- `backend/README.md` - API reference
-- `backend/example_usage.py` - Usage examples
-- `docs/BACKEND_IMPLEMENTATION.md` - Implementation details
-- `docs/COMPETITIVE_ANALYSIS.md` - vs. reference projects
-
-Happy building! 🚀
diff --git a/docs/BACKEND_IMPLEMENTATION.md b/docs/BACKEND_IMPLEMENTATION.md
deleted file mode 100644
index 2a1a8366..00000000
--- a/docs/BACKEND_IMPLEMENTATION.md
+++ /dev/null
@@ -1,368 +0,0 @@
-# Backend Implementation Summary
-
-Complete implementation of the voicebox backend based on analysis of reference projects.
-
-## What's Been Built
-
-### ✅ Core Modules (100% Complete)
-
-#### 1. TTS Module (`tts.py`)
-**Pattern Source:** mimic + Voice-Clone-Studio
-
-**Features:**
-- Lazy model loading with device detection (CPU/CUDA/MPS)
-- Voice prompt creation with dual caching (memory + disk)
-- Multi-reference combination for quality improvement
-- Async generation with seed control
-- Model size switching (1.7B/0.6B)
-- Proper memory management and cleanup
-
-**Key Improvements Over References:**
-- Cleaner async/await patterns than mimic
-- Better error handling than Voice-Clone-Studio
-- Proper type hints throughout
-- Modular design vs monolithic files
-
-#### 2. Profiles Module (`profiles.py`)
-**Pattern Source:** mimic + qwen3-tts-enhanced
-
-**Features:**
-- Full CRUD operations for voice profiles
-- Multi-sample support per profile
-- Audio validation before adding samples
-- Automatic sample combination for generation
-- File storage organization in `data/profiles/`
-- Database persistence with timestamps
-
-**Key Improvements:**
-- Better separation of concerns than mimic
-- Proper async implementation
-- Validation integrated at module level
-- Cleaner API than reference implementations
-
-#### 3. History Module (`history.py`)
-**Pattern Source:** mimic
-
-**Features:**
-- Generation history tracking with full metadata
-- Search and filtering capabilities
-- Pagination support
-- Statistics endpoint
-- Audio file cleanup on deletion
-- Profile-based filtering
-
-**Key Improvements:**
-- Returns total count for pagination
-- Statistics aggregation
-- Better query patterns
-- Proper cleanup of associated files
-
-#### 4. Transcribe Module (`transcribe.py`)
-**Pattern Source:** Voice-Clone-Studio + mimic
-
-**Features:**
-- Whisper model loading and transcription
-- Language hint support
-- Word-level timestamps (placeholder for full implementation)
-- Model size selection
-- VRAM management
-
-**Differences:**
-- Simplified vs Voice-Clone-Studio's complex setup
-- Prepared for future timestamp integration
-- Better device handling
-
-#### 5. Database Module (`database.py`)
-**Pattern Source:** mimic
-
-**Features:**
-- SQLite with SQLAlchemy ORM
-- Proper foreign key relationships
-- Automatic timestamp management
-- UUID primary keys
-- Clean session management
-
-**Schema:**
-- `profiles` - Voice profile metadata
-- `profile_samples` - Multi-sample support
-- `generations` - Complete generation history
-- `projects` - Future audio studio projects
-
-#### 6. Models Module (`models.py`)
-**Pattern Source:** Qwen3-TTS_server + mimic
-
-**Features:**
-- Pydantic v2 models for validation
-- Request/response models separated
-- Proper field validation
-- Type safety throughout
-- `from_attributes` for ORM compatibility
-
-#### 7. Utils Module
-
-##### `audio.py`
-**Pattern Source:** qwen3-tts-enhanced + Voice-Clone-Studio
-
-- RMS normalization with peak limiting
-- Audio loading with resampling
-- Audio saving in consistent format
-- Reference audio validation (duration, RMS, clipping)
-
-##### `cache.py`
-**Pattern Source:** Voice-Clone-Studio (their best pattern)
-
-- MD5-based cache key generation
-- Dual caching (memory + disk)
-- Automatic cache invalidation
-- Corrupted cache file handling
-- Persistent across server restarts
-
-##### `validation.py`
-**Pattern Source:** Original design
-
-- Text validation
-- Language code validation
-- File path validation
-- Reusable validation patterns
-
-### ✅ API Implementation (`main.py`)
-
-**Pattern Source:** Qwen3-TTS_server + mimic
-
-**Complete REST API:**
-- 20+ endpoints covering all features
-- Proper HTTP status codes
-- File upload handling
-- File serving for audio
-- Health check with model status
-- Model management endpoints
-- Error handling with details
-- CORS configuration
-
-**Endpoints Organized:**
-1. Health & Info (2)
-2. Voice Profiles (8)
-3. Generation (1)
-4. History (4)
-5. Audio Files (1)
-6. Transcription (1)
-7. Model Management (2)
-
-## Architecture Comparison
-
-### Reference Projects Analysis
-
-| Aspect | voice | Voice-Clone-Studio | Qwen3-TTS_server | mimic | voicebox |
-|--------|-------|-------------------|------------------|-------|----------|
-| **Code Organization** | Good | Poor (2815 lines) | Excellent | Backend: Good | Excellent |
-| **Type Safety** | Rust: Yes, Python: No | No | Partial | Partial | Full (Pydantic) |
-| **Async/Await** | No (subprocess) | No | Limited | Full | Full |
-| **Caching** | Voice prompts | Voice prompts + disk | None | None | Voice prompts + disk |
-| **Multi-Sample** | No | No | No | Yes | Yes |
-| **Database** | File-based | File-based | None | SQLite | SQLite |
-| **API Design** | HTTP basic | Gradio only | REST clean | REST good | REST excellent |
-| **Error Handling** | Good | Basic | Basic | Good | Excellent |
-| **File Lines** | ~500 | 2815 | ~800 | ~4000 | ~1500 |
-
-### What Makes voicebox Better
-
-#### 1. **Clean Architecture**
-- No monolithic files (largest file: ~300 lines in main.py)
-- Proper module separation
-- Each file has single responsibility
-- Easy to test and maintain
-
-#### 2. **Production-Ready Patterns**
-- Full async/await (not bolted on)
-- Proper error handling with context
-- Type safety throughout
-- Database transactions
-- Resource cleanup
-
-#### 3. **Best Patterns from Each Reference**
-- Voice prompt caching → Voice-Clone-Studio
-- Multi-sample profiles → qwen3-tts-enhanced + mimic
-- Audio normalization → qwen3-tts-enhanced
-- API structure → Qwen3-TTS_server
-- Database design → mimic
-- VRAM management → Voice-Clone-Studio
-
-#### 4. **Avoiding Reference Mistakes**
-- ❌ No 2000+ line files
-- ❌ No global mutable state
-- ❌ No code duplication
-- ❌ No mixed concerns
-- ❌ No poor error messages
-
-## API Feature Matrix
-
-| Feature | Implemented | Source Pattern |
-|---------|-------------|----------------|
-| Voice profile CRUD | ✅ | mimic |
-| Multi-sample profiles | ✅ | qwen3-tts-enhanced + mimic |
-| Voice prompt caching | ✅ | Voice-Clone-Studio |
-| Generation with seed | ✅ | All |
-| History tracking | ✅ | mimic |
-| History search | ✅ | mimic |
-| Transcription | ✅ | Voice-Clone-Studio |
-| Audio validation | ✅ | qwen3-tts-enhanced |
-| Model management | ✅ | Original |
-| File serving | ✅ | mimic |
-| Health checks | ✅ | Qwen3-TTS_server |
-| Statistics | ✅ | Original |
-| Batch generation | ⏳ | TODO |
-| WebSocket streaming | ⏳ | TODO |
-| Audio effects (M3GAN) | ⏳ | TODO |
-| Voice design | ⏳ | TODO |
-| Audio studio | ⏳ | TODO |
-| Projects | ⏳ | TODO |
-
-## File Structure
-
-```
-backend/
-├── main.py                 # 300 lines - FastAPI app + all routes
-├── models.py               # 100 lines - Pydantic models
-├── tts.py                  # 200 lines - TTS inference
-├── transcribe.py           # 150 lines - Whisper ASR
-├── profiles.py             # 250 lines - Profile management
-├── history.py              # 150 lines - History management
-├── studio.py               # 70 lines - Audio studio (skeleton)
-├── database.py             # 90 lines - SQLite ORM
-├── requirements.txt        # Dependencies
-├── README.md               # Complete API documentation
-├── example_usage.py        # Example client code
-└── utils/
-    ├── __init__.py
-    ├── audio.py            # 120 lines - Audio processing
-    ├── cache.py            # 90 lines - Voice prompt caching
-    └── validation.py       # 65 lines - Input validation
-
-Total: ~1,500 lines (clean, maintainable, type-safe)
-```
-
-Compare to references:
-- voice: ~500 lines (but limited features)
-- Voice-Clone-Studio: 2,815 lines in ONE file
-- Qwen3-TTS_server: ~800 lines (but no history/profiles)
-- mimic backend: ~1,200 lines (our closest match, but less clean)
-
-## Testing Strategy
-
-### Manual Testing
-1. Start server: `python -m backend.main`
-2. Run example: `python backend/example_usage.py`
-3. Test with curl/Postman
-
-### Unit Testing (TODO)
-```
-tests/
-├── test_tts.py
-├── test_profiles.py
-├── test_history.py
-├── test_transcribe.py
-├── test_audio.py
-└── test_cache.py
-```
-
-## Performance Characteristics
-
-### Voice Prompt Caching
-- **First generation:** ~5-10 seconds
-  - Load model: 3-5s
-  - Create prompt: 2-3s
-  - Generate: 1-2s
-
-- **Subsequent generations:** ~1-2 seconds
-  - Model loaded: 0s
-  - Prompt cached: 0s
-  - Generate: 1-2s
-
-### Multi-Sample Profiles
-- Combining 2-3 samples: +1-2 seconds on first use
-- Cached after first use
-- Better quality than single sample
-
-### Model Sizes
-- **1.7B:** Best quality, ~3GB VRAM, slower on CPU
-- **0.6B:** Good quality, ~1GB VRAM, faster on CPU
-
-## Next Steps
-
-### Phase 1: Testing & Polish
-1. Add unit tests
-2. Add integration tests
-3. Error handling edge cases
-4. Documentation improvements
-
-### Phase 2: Advanced Features
-1. Batch generation endpoint
-2. WebSocket for progress
-3. Audio effects (M3GAN, pitch, etc.)
-4. Voice design (text-to-voice)
-
-### Phase 3: Audio Studio
-1. Word-level timestamps (full implementation)
-2. Timeline mixing
-3. Trim/fade operations
-4. Project save/load
-5. Export options
-
-### Phase 4: Production Features
-1. Authentication & authorization
-2. Rate limiting
-3. Usage tracking
-4. Model caching strategies
-5. Distributed generation (multiple GPUs)
-
-## Deployment
-
-### Development
-```bash
-cd backend
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-python main.py
-```
-
-### Production
-```bash
-# Using uvicorn directly
-uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4
-
-# Or using gunicorn
-gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker
-```
-
-### Docker (TODO)
-```dockerfile
-FROM python:3.11
-# ... setup
-CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0"]
-```
-
-## Conclusion
-
-The voicebox backend is **production-ready** for:
-- ✅ Voice profile management
-- ✅ Multi-sample voice cloning
-- ✅ Generation history
-- ✅ Transcription
-- ✅ Basic audio processing
-
-It successfully combines:
-- **Best architecture** from mimic
-- **Best caching** from Voice-Clone-Studio
-- **Best audio processing** from qwen3-tts-enhanced
-- **Best API design** from Qwen3-TTS_server
-- **Best practices** from professional software engineering
-
-While avoiding:
-- ❌ Monolithic files
-- ❌ Global state
-- ❌ Poor separation of concerns
-- ❌ Code duplication
-- ❌ Weak typing
-
-The result is a clean, maintainable, production-quality backend that's ready for the Tauri frontend integration.
diff --git a/docs/BIOME_SETUP.md b/docs/BIOME_SETUP.md
deleted file mode 100644
index e1bead8d..00000000
--- a/docs/BIOME_SETUP.md
+++ /dev/null
@@ -1,268 +0,0 @@
-# Biome Setup Complete
-
-Biome v2.3.12 is now configured for voicebox.
-
-## What Was Configured
-
-### ✅ Installed
-- `@biomejs/biome@2.3.12` (exact version pinned)
-- Removed ESLint and all related dependencies
-
-### ✅ Configuration Files Created
-
-**`biome.json`** - Main configuration:
-- Formatter: 2-space indents, 100 char line width
-- Linter: Recommended rules + React best practices
-- JavaScript: Single quotes, double quotes for JSX
-- Tailwind CSS: `@tailwind` directives allowed
-
-**`.vscode/settings.json`** - IDE integration:
-- Biome as default formatter
-- Format on save enabled
-- Auto-import organization
-- Prettier and ESLint disabled
-
-**`.vscode/extensions.json`** - Recommended extensions:
-- Biome (biomejs.biome)
-- Tailwind CSS IntelliSense
-- Rust Analyzer
-- Tauri Extension
-
-**`.biomeignore`** - Ignored files:
-- `node_modules`, `dist`, `target`
-- Generated API client
-- Config files
-- Lock files
-
-### ✅ Package Scripts
-
-Run from root:
-```bash
-bun run lint          # Check linting issues
-bun run lint:fix      # Fix linting issues
-bun run format        # Format all files
-bun run format:check  # Check formatting
-bun run check         # Check everything (lint + format)
-bun run check:fix     # Fix everything
-bun run ci            # Strict check for CI/CD
-```
-
-Run from `app/`:
-```bash
-bun run lint          # Lint app/src
-bun run lint:fix      # Fix lint issues
-bun run format        # Format app/src
-bun run check         # Check app/src
-```
-
-## Current Status
-
-✅ **26 files checked**
-✅ **1 warning** (accessibility - safe to ignore for now)
-✅ **0 errors**
-
-The single warning is:
-```
-app/src/App.tsx:14:11 - Provide explicit type prop for button
-```
-
-This is a good accessibility practice but not blocking. Add `type="button"` when you build real components.
-
-## Biome vs ESLint + Prettier
-
-| Feature | Biome | ESLint + Prettier |
-|---------|-------|------------------|
-| Speed | ~15ms for 26 files | ~500ms+ |
-| Single tool | ✅ | ❌ (2 tools) |
-| TypeScript support | ✅ Native | ⚠️ Plugins needed |
-| JSON/CSS formatting | ✅ | ⚠️ Limited |
-| Auto-fix | ✅ | ⚠️ Partial |
-| Import sorting | ✅ Built-in | ❌ Needs plugin |
-
-## Configuration Highlights
-
-### Linting Rules
-
-**Enabled (errors):**
-- `noUnusedImports` - Remove unused imports
-- `noDoubleEquals` - Use `===` instead of `==`
-- `useHookAtTopLevel` - React hooks at component top level
-- `useExhaustiveDependencies` - Complete React hook deps
-
-**Enabled (warnings):**
-- `noUnusedVariables` - Warn on unused vars (not error)
-- `noExplicitAny` - Discourage `any` type
-- `useButtonType` - Accessibility for buttons
-
-**Disabled:**
-- `noNonNullAssertion` - Allow `!` in React (safe with `getElementById`)
-- `useFilenamingConvention` - Allow flexible naming
-- `noUnknownAtRules` - Allow Tailwind CSS directives
-
-### Formatting Style
-
-```typescript
-// Single quotes for JS/TS
-import { foo } from 'bar';
-
-// Double quotes for JSX
-<Component prop="value" />
-
-// Always semicolons
-const x = 5;
-
-// Always arrow parens
-const fn = (x) => x + 1;
-
-// Trailing commas
-const obj = {
-  a: 1,
-  b: 2,
-};
-```
-
-## VS Code Integration
-
-1. **Install extension:**
-   - Search "Biome" in VS Code extensions
-   - Install "Biome" by Biomejs
-
-2. **Automatic:**
-   - Format on save ✅
-   - Auto-import organization ✅
-   - Inline errors/warnings ✅
-   - Quick fixes ✅
-
-3. **Manual formatting:**
-   - macOS: `⇧⌥F`
-   - Windows/Linux: `Shift+Alt+F`
-
-## CI/CD Integration
-
-Add to GitHub Actions:
-
-```yaml
-- name: Setup Bun
-  uses: oven-sh/setup-bun@v2
-
-- name: Install dependencies
-  run: bun install
-
-- name: Check code quality
-  run: bun run ci
-```
-
-The `ci` command is strict and fails if any fixes are needed.
-
-## Migration Notes
-
-### Removed
-- ❌ `eslint`
-- ❌ `@typescript-eslint/eslint-plugin`
-- ❌ `@typescript-eslint/parser`
-- ❌ `eslint-plugin-react-hooks`
-- ❌ `eslint-plugin-react-refresh`
-- ❌ `.eslintrc.cjs`
-
-### Why Biome?
-
-From your CLAUDE.md:
-> "You are a senior software engineer specializing in Rust and TypeScript. You pride yourself on clean production ready code."
-
-Biome is:
-- **Written in Rust** - Aligns with your stack (Tauri is Rust)
-- **Fast** - 20-30x faster than ESLint
-- **Simple** - One tool instead of two (ESLint + Prettier)
-- **Production-ready** - Used by Meta, Vercel, and other large teams
-- **Type-aware** - Understands TypeScript natively
-
-## Common Commands
-
-```bash
-# Format everything
-bun run format
-
-# Fix all auto-fixable issues
-bun run check:fix
-
-# Check before commit (no changes)
-bun run ci
-
-# Format specific file
-bunx biome format --write app/src/App.tsx
-
-# Check specific directory
-bunx biome check app/src/components
-```
-
-## Advanced Configuration
-
-### Add custom rules
-
-Edit `biome.json`:
-```json
-{
-  "linter": {
-    "rules": {
-      "complexity": {
-        "noExcessiveCognitiveComplexity": {
-          "level": "error",
-          "options": {
-            "maxAllowedComplexity": 15
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Per-file configuration
-
-Use `overrides` in `biome.json`:
-```json
-{
-  "overrides": [
-    {
-      "includes": ["app/src/lib/api/**"],
-      "linter": {
-        "enabled": false
-      }
-    }
-  ]
-}
-```
-
-## Troubleshooting
-
-### Biome not formatting in VS Code
-
-1. Open Command Palette (`Cmd+Shift+P`)
-2. Search "Format Document With..."
-3. Select "Biome"
-4. Check if Biome extension is installed
-
-### Conflicts with Prettier
-
-Make sure Prettier is disabled in VS Code settings (already configured in `.vscode/settings.json`).
-
-### Performance issues
-
-Biome is extremely fast, but if you experience issues:
-```bash
-# Clear Biome cache
-rm -rf .biome-cache
-
-# Reinstall
-bun remove @biomejs/biome
-bun add -D -E @biomejs/biome
-```
-
-## Next Steps
-
-1. ✅ Biome is ready to use
-2. ✅ Run `bun run format` to format existing code
-3. ✅ Install Biome VS Code extension
-4. 🚀 Start building frontend components
-
-All future code will be automatically formatted and linted on save!
diff --git a/docs/COMPETITIVE_ANALYSIS.md b/docs/COMPETITIVE_ANALYSIS.md
deleted file mode 100644
index 72d41662..00000000
--- a/docs/COMPETITIVE_ANALYSIS.md
+++ /dev/null
@@ -1,377 +0,0 @@
-# Competitive Analysis: voicebox vs Reference Implementations
-
-Detailed comparison showing how voicebox improves upon each reference project.
-
-## Executive Summary
-
-voicebox combines the **best patterns** from 5 reference implementations while avoiding their **architectural mistakes**. The result is a production-quality system that's maintainable, type-safe, and feature-rich.
-
----
-
-## 1. vs. voice (Rust CLI)
-
-### What voice Does Well
-- ✅ Clean Rust/Python separation
-- ✅ M3GAN voice effect
-- ✅ Voice profile abstraction
-- ✅ Good error handling in Rust
-
-### What voicebox Does Better
-| Aspect | voice | voicebox |
-|--------|-------|----------|
-| **Concurrency** | Spawns subprocess per request | Async with persistent model |
-| **Caching** | Voice prompts only | Voice prompts + disk |
-| **History** | None | Full database with search |
-| **API** | Basic HTTP | Full REST with 20+ endpoints |
-| **Multi-sample** | No | Yes |
-| **Type safety** | Python: No | Full Pydantic |
-| **Database** | File-based | SQLite with migrations |
-
-### Architecture Comparison
-```
-voice:
-Rust HTTP → spawn Python → JSON IPC → generate → return
-
-voicebox:
-FastAPI → async TTS → cached prompt → generate → save to DB
-```
-
-**Winner:** voicebox (persistent models, caching, database)
-
----
-
-## 2. vs. Voice-Clone-Studio (Gradio)
-
-### What Voice-Clone-Studio Does Well
-- ✅ Brilliant voice prompt caching (memory + disk)
-- ✅ Dual engine support (Qwen + VibeVoice)
-- ✅ Feature-rich (voice design, presets, conversations)
-- ✅ VRAM efficiency (smart loading/unloading)
-- ✅ Metadata tracking
-
-### What voicebox Does Better
-| Aspect | Voice-Clone-Studio | voicebox |
-|--------|-------------------|----------|
-| **Code organization** | 2,815 lines in ONE file | ~1,500 lines across 12 files |
-| **State management** | Global mutable state | Proper dependency injection |
-| **Type safety** | None | Full Pydantic + type hints |
-| **Testing** | Impossible | Easy (modular) |
-| **API** | Gradio only | REST + future WebSocket |
-| **Separation of concerns** | All mixed | Clean modules |
-| **Error handling** | Generic messages | Contextual errors |
-| **Code duplication** | 5 identical model loaders | Single abstraction |
-
-### Code Quality Comparison
-```python
-# Voice-Clone-Studio
-def generate_voice_clone(...):  # Line 450
-    global _tts_model, _whisper_model
-    if _whisper_model:
-        del _whisper_model
-    _whisper_model = None
-    # ... 200 more lines of mixed logic
-
-# voicebox
-async def generate(self, text: str, voice_prompt: dict, ...) -> Tuple[np.ndarray, int]:
-    """Generate audio from text using voice prompt."""
-    self.load_model()
-    # ... clean, focused logic
-```
-
-**Winner:** voicebox (maintainable architecture)
-
----
-
-## 3. vs. Qwen3-TTS_server (FastAPI)
-
-### What Qwen3-TTS_server Does Well
-- ✅ Clean API design
-- ✅ Proper separation (routes, models, utils)
-- ✅ Singleton model manager
-- ✅ Health endpoint
-- ✅ Docker deployment
-- ✅ Base64 audio input
-
-### What voicebox Does Better
-| Aspect | Qwen3-TTS_server | voicebox |
-|--------|-----------------|----------|
-| **Authentication** | None | TODO (planned) |
-| **Rate limiting** | None | TODO (planned) |
-| **Concurrency** | Sequential | Async throughout |
-| **Caching** | None | Voice prompts cached |
-| **Streaming** | No | TODO (WebSocket planned) |
-| **Storage** | Temporary | Persistent database |
-| **History** | None | Full tracking + search |
-| **Profiles** | None | Full CRUD + samples |
-| **Error handling** | Basic | Detailed + contextual |
-| **Features** | 3 endpoints | 20+ endpoints |
-
-### Feature Matrix
-| Feature | Qwen3-TTS_server | voicebox |
-|---------|-----------------|----------|
-| Generate | ✅ | ✅ |
-| Clone | ✅ | ✅ |
-| Health | ✅ | ✅ |
-| Profiles | ❌ | ✅ |
-| Multi-sample | ❌ | ✅ |
-| History | ❌ | ✅ |
-| Search | ❌ | ✅ |
-| Transcription | ❌ | ✅ |
-| File serving | ❌ | ✅ |
-| Statistics | ❌ | ✅ |
-
-**Winner:** voicebox (far more features)
-
----
-
-## 4. vs. mimic (Web App)
-
-### What mimic Does Well
-- ✅ **Best backend structure** of all references
-- ✅ Async/await throughout
-- ✅ Database-backed persistence
-- ✅ Audio studio with timeline
-- ✅ Word-level timestamps
-- ✅ Project system
-- ✅ Full-text search
-
-### What voicebox Does Better
-| Aspect | mimic | voicebox |
-|--------|-------|----------|
-| **Type safety** | Partial | Full Pydantic |
-| **Caching** | None | Voice prompts |
-| **Multi-sample** | Basic | Advanced (combination) |
-| **Audio validation** | Limited | Comprehensive |
-| **API docs** | Basic | Auto-generated OpenAPI |
-| **Model management** | Manual | Lazy + auto-cleanup |
-| **Error messages** | Generic | Detailed + actionable |
-| **Code organization** | Good | Excellent |
-
-### Backend Comparison
-```
-mimic backend:
-~1,200 lines, async, modular, but:
-- No caching
-- Basic multi-sample
-- No audio validation
-- Manual model management
-
-voicebox backend:
-~1,500 lines, async, modular, plus:
-- Voice prompt caching
-- Advanced multi-sample with combination
-- Comprehensive validation
-- Automatic lazy loading
-```
-
-### Where mimic is Still Ahead
-- ⚠️ **Audio studio** - Timeline editing, mixing
-- ⚠️ **Word timestamps** - Full implementation
-- ⚠️ **Projects** - Save/load sessions
-
-**Planned for voicebox Phase 3**
-
-**Winner:** voicebox (backend), but mimic has features we'll add later
-
----
-
-## 5. vs. qwen3-tts-enhanced (Gradio)
-
-### What qwen3-tts-enhanced Does Well
-- ✅ Multi-reference cloning
-- ✅ Batch variations
-- ✅ Smart audio normalization
-- ✅ Cross-platform support
-- ✅ Backward compatibility
-- ✅ Audio validation
-- ✅ Quality presets
-- ✅ Clean code (despite being monolithic)
-- ✅ Good error messages
-
-### What voicebox Does Better
-| Aspect | qwen3-tts-enhanced | voicebox |
-|--------|-------------------|----------|
-| **Architecture** | 1,892 lines in one file | 12 modular files |
-| **Database** | File-based | SQLite |
-| **History** | None | Full tracking |
-| **API** | Gradio only | REST API |
-| **Concurrency** | One at a time | Async support |
-| **Profiles** | File-based | Database CRUD |
-
-### What We Adopted
-- ✅ Multi-reference combination
-- ✅ Audio validation patterns
-- ✅ RMS normalization
-- ✅ Cross-platform audio handling
-- ✅ Good error messages
-
-**Winner:** voicebox (better architecture, adopted best features)
-
----
-
-## Composite Feature Matrix
-
-| Feature | voice | Voice-Clone-Studio | Qwen3-TTS_server | mimic | qwen3-tts-enhanced | **voicebox** |
-|---------|-------|-------------------|------------------|-------|-------------------|--------------|
-| **Architecture** | | | | | | |
-| Modular code | ⚠️ | ❌ | ✅ | ✅ | ⚠️ | ✅ |
-| Type safety | ⚠️ | ❌ | ⚠️ | ⚠️ | ❌ | ✅ |
-| Async/await | ❌ | ❌ | ⚠️ | ✅ | ❌ | ✅ |
-| Database | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
-| REST API | ⚠️ | ❌ | ✅ | ✅ | ❌ | ✅ |
-| **Features** | | | | | | |
-| Voice cloning | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Multi-sample | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
-| Voice prompt cache | ⚠️ | ✅ | ❌ | ❌ | ⚠️ | ✅ |
-| History tracking | ❌ | ⚠️ | ❌ | ✅ | ❌ | ✅ |
-| Search | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
-| Transcription | ❌ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Audio validation | ❌ | ❌ | ❌ | ⚠️ | ✅ | ✅ |
-| Audio studio | ❌ | ❌ | ❌ | ✅ | ❌ | ⏳ |
-| Voice design | ❌ | ✅ | ❌ | ❌ | ❌ | ⏳ |
-| M3GAN effect | ✅ | ❌ | ❌ | ❌ | ❌ | ⏳ |
-| **Quality** | | | | | | |
-| Multi-reference | ❌ | ❌ | ❌ | ⚠️ | ✅ | ✅ |
-| Normalization | ❌ | ⚠️ | ❌ | ⚠️ | ✅ | ✅ |
-| Quality presets | ❌ | ❌ | ❌ | ❌ | ✅ | ⏳ |
-| **Production** | | | | | | |
-| Error handling | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ✅ |
-| Health checks | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |
-| Model management | ⚠️ | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ |
-| Docker ready | ❌ | ❌ | ✅ | ❌ | ❌ | ⏳ |
-
-Legend:
-- ✅ Excellent/Complete
-- ⚠️ Partial/Basic
-- ❌ Missing/Poor
-- ⏳ Planned
-
----
-
-## Code Quality Metrics
-
-### Lines of Code
-| Project | Total Lines | Largest File | Files |
-|---------|------------|--------------|-------|
-| voice | ~500 | main.rs (200) | 5 |
-| Voice-Clone-Studio | 2,815 | voice_clone_studio.py (2,815) | 1 |
-| Qwen3-TTS_server | ~800 | server.py (400) | 4 |
-| mimic backend | ~1,200 | app.js (2,794) | 7 |
-| qwen3-tts-enhanced | 1,892 | app.py (1,892) | 1 |
-| **voicebox** | **~1,500** | **main.py (300)** | **12** |
-
-### Maintainability Score
-| Project | Organization | Type Safety | Modularity | Testing | Total |
-|---------|-------------|-------------|------------|---------|-------|
-| voice | 7/10 | 5/10 | 7/10 | 0/10 | **19/40** |
-| Voice-Clone-Studio | 2/10 | 0/10 | 1/10 | 0/10 | **3/40** |
-| Qwen3-TTS_server | 9/10 | 5/10 | 9/10 | 0/10 | **23/40** |
-| mimic | 8/10 | 5/10 | 8/10 | 0/10 | **21/40** |
-| qwen3-tts-enhanced | 6/10 | 3/10 | 3/10 | 0/10 | **12/40** |
-| **voicebox** | **10/10** | **10/10** | **10/10** | **3/10** | **33/40** |
-
----
-
-## Performance Comparison
-
-### Voice Prompt Generation
-| Project | First Gen | Cached Gen | Cache Type |
-|---------|-----------|------------|------------|
-| voice | 8-12s | 8-12s | None |
-| Voice-Clone-Studio | 6-10s | 1-2s | Memory + Disk |
-| Qwen3-TTS_server | 8-12s | 8-12s | None |
-| mimic | 8-12s | 8-12s | None |
-| qwen3-tts-enhanced | 6-10s | 6-10s | Basic |
-| **voicebox** | **6-10s** | **1-2s** | **Memory + Disk** |
-
-### Multi-Sample Combination
-| Project | Supports | Method | Quality |
-|---------|----------|--------|---------|
-| voice | ❌ | - | - |
-| Voice-Clone-Studio | ❌ | - | - |
-| Qwen3-TTS_server | ❌ | - | - |
-| mimic | ✅ | Simple concat | Good |
-| qwen3-tts-enhanced | ✅ | Normalized concat | Excellent |
-| **voicebox** | ✅ | **Normalized concat** | **Excellent** |
-
----
-
-## What voicebox Achieves
-
-### Combines Best of All References
-1. **Architecture** from mimic + Qwen3-TTS_server
-2. **Caching** from Voice-Clone-Studio
-3. **Audio processing** from qwen3-tts-enhanced
-4. **Effects** from voice (planned)
-5. **Features** from all projects
-
-### Avoids All Major Pitfalls
-1. ❌ No monolithic files (Voice-Clone-Studio, qwen3-tts-enhanced)
-2. ❌ No global state (Voice-Clone-Studio, voice)
-3. ❌ No synchronous blocking (voice, Voice-Clone-Studio)
-4. ❌ No missing features (Qwen3-TTS_server)
-5. ❌ No poor separation (Voice-Clone-Studio)
-
-### Production-Ready From Day One
-- ✅ Type-safe with Pydantic
-- ✅ Async/await throughout
-- ✅ Proper error handling
-- ✅ Database persistence
-- ✅ Clean architecture
-- ✅ Easy to test
-- ✅ Auto-generated API docs
-- ✅ Health monitoring
-
----
-
-## Future Roadmap
-
-### Phase 1: Current State ✅
-- [x] Core TTS with caching
-- [x] Profile management
-- [x] Multi-sample support
-- [x] History tracking
-- [x] Transcription
-- [x] REST API
-
-### Phase 2: Next Quarter
-- [ ] WebSocket streaming
-- [ ] Batch generation
-- [ ] Audio effects (M3GAN)
-- [ ] Voice design
-- [ ] Unit tests (80% coverage)
-
-### Phase 3: Following Quarter
-- [ ] Audio studio (from mimic)
-- [ ] Word-level timestamps
-- [ ] Project management
-- [ ] Export options
-
-### Phase 4: Production
-- [ ] Authentication
-- [ ] Rate limiting
-- [ ] Docker deployment
-- [ ] CI/CD pipeline
-- [ ] Monitoring & logging
-
----
-
-## Conclusion
-
-voicebox backend is:
-
-1. **Most maintainable** - Clean architecture, modular, type-safe
-2. **Most feature-rich** - Combines features from all references
-3. **Best performance** - Caching + async + proper pooling
-4. **Production-ready** - Error handling, health checks, monitoring
-5. **Future-proof** - Easy to extend, test, deploy
-
-It's the **only implementation** that combines:
-- ✅ Clean code (Qwen3-TTS_server)
-- ✅ Advanced caching (Voice-Clone-Studio)
-- ✅ Quality audio (qwen3-tts-enhanced)
-- ✅ Full features (mimic)
-- ✅ Type safety (none had this)
-- ✅ Production patterns (our innovation)
-
-**Result:** A professional-grade system ready for the Tauri frontend and real-world deployment.
diff --git a/docs/FRONTEND_PLAN.md b/docs/FRONTEND_PLAN.md
deleted file mode 100644
index 18a28be3..00000000
--- a/docs/FRONTEND_PLAN.md
+++ /dev/null
@@ -1,1334 +0,0 @@
-# Frontend Implementation Plan
-
-Complete plan for building the voicebox frontend with modern React, TypeScript, shadcn/ui, and full type safety.
-
----
-
-## Technology Stack
-
-### Core
-- **React 18** - UI framework with concurrent features
-- **TypeScript (strict mode)** - Full type safety
-- **Vite** - Fast build tool and dev server
-- **Bun** - Package manager
-
-### UI & Styling
-- **shadcn/ui** - Headless component primitives (new-york style)
-- **Tailwind CSS v4** - Utility-first styling
-- **Radix UI** - Accessible primitives (via shadcn/ui)
-- **Lucide React** - Icon system
-- **class-variance-authority (cva)** - Component variants
-- **tailwind-merge** - Smart class merging
-
-### State Management
-- **React Query v5** - Server state (API calls, caching)
-- **Zustand** - Client state (UI state, modals, selections)
-- **React Hook Form** - Form state and validation
-- **Zod** - Runtime schema validation
-
-### Audio
-- **WaveSurfer.js** - Audio waveform visualization
-- **Web Audio API** - Audio recording/playback
-- **MediaRecorder API** - Voice recording
-
-### Type Safety
-- **OpenAPI TypeScript Codegen** - Generate API client from FastAPI schema
-- **Zod** - Runtime validation matching backend Pydantic models
-- **TypeScript strict mode** - Compiler enforcement
-
----
-
-## Architecture Overview
-
-```
-app/src/
-├── components/
-│   ├── ui/                    # shadcn/ui primitives (auto-generated)
-│   │   ├── button.tsx
-│   │   ├── dialog.tsx
-│   │   ├── form.tsx
-│   │   ├── input.tsx
-│   │   ├── select.tsx
-│   │   ├── slider.tsx
-│   │   ├── table.tsx
-│   │   ├── tabs.tsx
-│   │   ├── card.tsx
-│   │   ├── badge.tsx
-│   │   ├── toast.tsx
-│   │   └── ...
-│   │
-│   ├── VoiceProfiles/         # Voice profile management
-│   │   ├── ProfileList.tsx
-│   │   ├── ProfileCard.tsx
-│   │   ├── ProfileForm.tsx
-│   │   ├── SampleUpload.tsx
-│   │   └── SampleList.tsx
-│   │
-│   ├── Generation/            # Voice generation
-│   │   ├── GenerationForm.tsx
-│   │   ├── GenerationPreview.tsx
-│   │   └── GenerationSettings.tsx
-│   │
-│   ├── History/               # Generation history
-│   │   ├── HistoryTable.tsx
-│   │   ├── HistoryFilter.tsx
-│   │   └── HistoryPlayer.tsx
-│   │
-│   ├── AudioStudio/           # Audio editing (Phase 3)
-│   │   ├── Timeline.tsx
-│   │   ├── Waveform.tsx
-│   │   ├── Controls.tsx
-│   │   └── TrackList.tsx
-│   │
-│   └── ServerSettings/        # Server connection
-│       ├── ConnectionForm.tsx
-│       ├── ServerStatus.tsx
-│       └── LocalServerToggle.tsx
-│
-├── lib/
-│   ├── api/                   # Generated OpenAPI client
-│   │   ├── core/
-│   │   ├── models/
-│   │   └── services/
-│   │       ├── ProfilesService.ts
-│   │       ├── GenerationService.ts
-│   │       └── HistoryService.ts
-│   │
-│   ├── hooks/                 # React Query hooks
-│   │   ├── useProfiles.ts
-│   │   ├── useGeneration.ts
-│   │   ├── useHistory.ts
-│   │   ├── useTranscription.ts
-│   │   └── useServer.ts
-│   │
-│   ├── schemas/               # Zod schemas (match backend)
-│   │   ├── profile.ts
-│   │   ├── generation.ts
-│   │   └── history.ts
-│   │
-│   └── utils/
-│       ├── cn.ts              # Class name utility (shadcn)
-│       ├── audio.ts           # Audio utilities
-│       └── format.ts          # Formatting helpers
-│
-├── stores/                    # Zustand stores
-│   ├── uiStore.ts            # UI state (modals, sidebar)
-│   ├── playerStore.ts        # Audio player state
-│   └── serverStore.ts        # Server connection state
-│
-├── types/                     # TypeScript types
-│   ├── index.ts
-│   ├── api.ts                # Augment generated types
-│   └── tauri.ts              # Tauri-specific types
-│
-├── App.tsx                    # Main app component
-├── main.tsx                   # Entry point
-└── index.css                  # Global styles + Tailwind
-```
-
----
-
-## Setup Steps
-
-### 1. Install shadcn/ui and Dependencies
-
-```bash
-cd app
-
-# Core dependencies (if not installed)
-bun add @tanstack/react-query zustand react-hook-form zod @hookform/resolvers wavesurfer.js
-
-# shadcn/ui setup
-bunx --bun shadcn-ui@latest init
-
-# Select:
-# - Style: new-york
-# - Base color: slate (or zinc for darker theme)
-# - CSS variables: yes
-```
-
-This creates:
-- `components.json` - shadcn/ui configuration
-- `components/ui/` - UI primitives directory
-- Installs: `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, `tailwindcss-animate`
-
-### 2. Update Vite Config
-
-**app/vite.config.ts:**
-```typescript
-import path from 'node:path';
-import react from '@vitejs/plugin-react';
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
-    },
-  },
-});
-```
-
-### 3. Update TypeScript Config
-
-**app/tsconfig.json:**
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "skipLibCheck": true,
-
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src"],
-  "references": [{ "path": "./tsconfig.node.json" }]
-}
-```
-
-### 4. Add Essential shadcn/ui Components
-
-```bash
-# Forms and inputs
-bunx --bun shadcn-ui@latest add button
-bunx --bun shadcn-ui@latest add input
-bunx --bun shadcn-ui@latest add form
-bunx --bun shadcn-ui@latest add label
-bunx --bun shadcn-ui@latest add select
-bunx --bun shadcn-ui@latest add textarea
-bunx --bun shadcn-ui@latest add slider
-
-# Layout and display
-bunx --bun shadcn-ui@latest add card
-bunx --bun shadcn-ui@latest add tabs
-bunx --bun shadcn-ui@latest add separator
-bunx --bun shadcn-ui@latest add badge
-bunx --bun shadcn-ui@latest add avatar
-
-# Feedback
-bunx --bun shadcn-ui@latest add toast
-bunx --bun shadcn-ui@latest add alert
-bunx --bun shadcn-ui@latest add progress
-
-# Overlays
-bunx --bun shadcn-ui@latest add dialog
-bunx --bun shadcn-ui@latest add dropdown-menu
-bunx --bun shadcn-ui@latest add popover
-
-# Data display
-bunx --bun shadcn-ui@latest add table
-bunx --bun shadcn-ui@latest add scroll-area
-```
-
-### 5. Setup Providers
-
-**app/src/main.tsx:**
-```typescript
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
-import App from './App';
-import './index.css';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <App />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  </React.StrictMode>,
-);
-```
-
-### 6. Setup Zustand Stores
-
-**app/src/stores/uiStore.ts:**
-```typescript
-import { create } from 'zustand';
-
-interface UIStore {
-  // Sidebar
-  sidebarOpen: boolean;
-  setSidebarOpen: (open: boolean) => void;
-
-  // Modals
-  profileDialogOpen: boolean;
-  setProfileDialogOpen: (open: boolean) => void;
-
-  generationDialogOpen: boolean;
-  setGenerationDialogOpen: (open: boolean) => void;
-
-  // Theme
-  theme: 'light' | 'dark';
-  setTheme: (theme: 'light' | 'dark') => void;
-}
-
-export const useUIStore = create<UIStore>((set) => ({
-  sidebarOpen: true,
-  setSidebarOpen: (open) => set({ sidebarOpen: open }),
-
-  profileDialogOpen: false,
-  setProfileDialogOpen: (open) => set({ profileDialogOpen: open }),
-
-  generationDialogOpen: false,
-  setGenerationDialogOpen: (open) => set({ generationDialogOpen: open }),
-
-  theme: 'light',
-  setTheme: (theme) => set({ theme }),
-}));
-```
-
-**app/src/stores/serverStore.ts:**
-```typescript
-import { create } from 'zustand';
-import { persist } from 'zustand/middleware';
-
-interface ServerStore {
-  serverUrl: string;
-  setServerUrl: (url: string) => void;
-
-  isConnected: boolean;
-  setIsConnected: (connected: boolean) => void;
-
-  mode: 'local' | 'remote';
-  setMode: (mode: 'local' | 'remote') => void;
-}
-
-export const useServerStore = create<ServerStore>()(
-  persist(
-    (set) => ({
-      serverUrl: 'http://localhost:8000',
-      setServerUrl: (url) => set({ serverUrl: url }),
-
-      isConnected: false,
-      setIsConnected: (connected) => set({ isConnected: connected }),
-
-      mode: 'local',
-      setMode: (mode) => set({ mode }),
-    }),
-    {
-      name: 'voicebox-server',
-    },
-  ),
-);
-```
-
----
-
-## React Query Hooks
-
-### useProfiles Hook
-
-**app/src/lib/hooks/useProfiles.ts:**
-```typescript
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { ProfilesService } from '@/lib/api/services/ProfilesService';
-import type { VoiceProfileCreate, VoiceProfileResponse } from '@/lib/api/models';
-
-export function useProfiles() {
-  return useQuery({
-    queryKey: ['profiles'],
-    queryFn: () => ProfilesService.listProfiles(),
-  });
-}
-
-export function useProfile(profileId: string) {
-  return useQuery({
-    queryKey: ['profiles', profileId],
-    queryFn: () => ProfilesService.getProfile({ profileId }),
-    enabled: !!profileId,
-  });
-}
-
-export function useCreateProfile() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: VoiceProfileCreate) =>
-      ProfilesService.createProfile({ data }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['profiles'] });
-    },
-  });
-}
-
-export function useUpdateProfile() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: ({ profileId, data }: { profileId: string; data: VoiceProfileCreate }) =>
-      ProfilesService.updateProfile({ profileId, data }),
-    onSuccess: (_, variables) => {
-      queryClient.invalidateQueries({ queryKey: ['profiles'] });
-      queryClient.invalidateQueries({ queryKey: ['profiles', variables.profileId] });
-    },
-  });
-}
-
-export function useDeleteProfile() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (profileId: string) =>
-      ProfilesService.deleteProfile({ profileId }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['profiles'] });
-    },
-  });
-}
-
-export function useAddSample() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: ({
-      profileId,
-      file,
-      referenceText
-    }: {
-      profileId: string;
-      file: File;
-      referenceText: string;
-    }) =>
-      ProfilesService.addProfileSample({
-        profileId,
-        file,
-        referenceText,
-      }),
-    onSuccess: (_, variables) => {
-      queryClient.invalidateQueries({
-        queryKey: ['profiles', variables.profileId, 'samples']
-      });
-    },
-  });
-}
-```
-
-### useGeneration Hook
-
-**app/src/lib/hooks/useGeneration.ts:**
-```typescript
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { GenerationService } from '@/lib/api/services/GenerationService';
-import type { GenerationRequest } from '@/lib/api/models';
-
-export function useGeneration() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: GenerationRequest) =>
-      GenerationService.generateSpeech({ data }),
-    onSuccess: () => {
-      // Invalidate history to show new generation
-      queryClient.invalidateQueries({ queryKey: ['history'] });
-    },
-  });
-}
-```
-
-### useHistory Hook
-
-**app/src/lib/hooks/useHistory.ts:**
-```typescript
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { HistoryService } from '@/lib/api/services/HistoryService';
-import type { HistoryQuery } from '@/lib/api/models';
-
-export function useHistory(query?: HistoryQuery) {
-  return useQuery({
-    queryKey: ['history', query],
-    queryFn: () => HistoryService.listHistory(query),
-  });
-}
-
-export function useGeneration(generationId: string) {
-  return useQuery({
-    queryKey: ['history', generationId],
-    queryFn: () => HistoryService.getGeneration({ generationId }),
-    enabled: !!generationId,
-  });
-}
-
-export function useDeleteGeneration() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (generationId: string) =>
-      HistoryService.deleteGeneration({ generationId }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['history'] });
-    },
-  });
-}
-```
-
----
-
-## Component Implementation
-
-### Phase 1: Voice Profiles (Week 1)
-
-#### ProfileList Component
-
-**app/src/components/VoiceProfiles/ProfileList.tsx:**
-```typescript
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Button } from '@/components/ui/button';
-import { Badge } from '@/components/ui/badge';
-import { Mic, Plus, Trash2 } from 'lucide-react';
-import { useProfiles, useDeleteProfile } from '@/lib/hooks/useProfiles';
-import { useUIStore } from '@/stores/uiStore';
-import { ProfileForm } from './ProfileForm';
-
-export function ProfileList() {
-  const { data: profiles, isLoading } = useProfiles();
-  const deleteProfile = useDeleteProfile();
-  const setDialogOpen = useUIStore((state) => state.setProfileDialogOpen);
-
-  if (isLoading) {
-    return <div>Loading profiles...</div>;
-  }
-
-  return (
-    <div className="space-y-4">
-      <div className="flex items-center justify-between">
-        <h2 className="text-2xl font-bold">Voice Profiles</h2>
-        <Button onClick={() => setDialogOpen(true)}>
-          <Plus className="mr-2 h-4 w-4" />
-          New Profile
-        </Button>
-      </div>
-
-      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
-        {profiles?.map((profile) => (
-          <Card key={profile.id}>
-            <CardHeader>
-              <CardTitle className="flex items-center justify-between">
-                <span className="flex items-center gap-2">
-                  <Mic className="h-5 w-5" />
-                  {profile.name}
-                </span>
-                <Button
-                  variant="ghost"
-                  size="icon"
-                  onClick={() => deleteProfile.mutate(profile.id)}
-                >
-                  <Trash2 className="h-4 w-4 text-destructive" />
-                </Button>
-              </CardTitle>
-            </CardHeader>
-            <CardContent>
-              <p className="text-sm text-muted-foreground">
-                {profile.description}
-              </p>
-              <div className="mt-2 flex gap-2">
-                <Badge variant="outline">{profile.language}</Badge>
-                <Badge variant="secondary">
-                  {profile.sample_count} samples
-                </Badge>
-              </div>
-            </CardContent>
-          </Card>
-        ))}
-      </div>
-
-      <ProfileForm />
-    </div>
-  );
-}
-```
-
-#### ProfileForm Component
-
-**app/src/components/VoiceProfiles/ProfileForm.tsx:**
-```typescript
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import * as z from 'zod';
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
-import {
-  Form,
-  FormControl,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormMessage,
-} from '@/components/ui/form';
-import { Input } from '@/components/ui/input';
-import { Textarea } from '@/components/ui/textarea';
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import { Button } from '@/components/ui/button';
-import { useCreateProfile } from '@/lib/hooks/useProfiles';
-import { useUIStore } from '@/stores/uiStore';
-
-const profileSchema = z.object({
-  name: z.string().min(1, 'Name is required').max(100),
-  description: z.string().optional(),
-  language: z.enum(['en', 'zh']),
-  tags: z.string().optional(),
-});
-
-type ProfileFormValues = z.infer<typeof profileSchema>;
-
-export function ProfileForm() {
-  const open = useUIStore((state) => state.profileDialogOpen);
-  const setOpen = useUIStore((state) => state.setProfileDialogOpen);
-  const createProfile = useCreateProfile();
-
-  const form = useForm<ProfileFormValues>({
-    resolver: zodResolver(profileSchema),
-    defaultValues: {
-      name: '',
-      description: '',
-      language: 'en',
-      tags: '',
-    },
-  });
-
-  async function onSubmit(data: ProfileFormValues) {
-    const tags = data.tags ? data.tags.split(',').map((t) => t.trim()) : [];
-
-    await createProfile.mutateAsync({
-      ...data,
-      tags,
-    });
-
-    form.reset();
-    setOpen(false);
-  }
-
-  return (
-    <Dialog open={open} onOpenChange={setOpen}>
-      <DialogContent>
-        <DialogHeader>
-          <DialogTitle>Create Voice Profile</DialogTitle>
-          <DialogDescription>
-            Add a new voice profile with samples
-          </DialogDescription>
-        </DialogHeader>
-
-        <Form {...form}>
-          <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-            <FormField
-              control={form.control}
-              name="name"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Name</FormLabel>
-                  <FormControl>
-                    <Input placeholder="My Voice" {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="description"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Description</FormLabel>
-                  <FormControl>
-                    <Textarea
-                      placeholder="Describe this voice..."
-                      {...field}
-                    />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="language"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Language</FormLabel>
-                  <Select
-                    onValueChange={field.onChange}
-                    defaultValue={field.value}
-                  >
-                    <FormControl>
-                      <SelectTrigger>
-                        <SelectValue />
-                      </SelectTrigger>
-                    </FormControl>
-                    <SelectContent>
-                      <SelectItem value="en">English</SelectItem>
-                      <SelectItem value="zh">Chinese</SelectItem>
-                    </SelectContent>
-                  </Select>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="tags"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Tags</FormLabel>
-                  <FormControl>
-                    <Input
-                      placeholder="tag1, tag2, tag3"
-                      {...field}
-                    />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <div className="flex gap-2">
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => setOpen(false)}
-              >
-                Cancel
-              </Button>
-              <Button
-                type="submit"
-                disabled={createProfile.isPending}
-              >
-                {createProfile.isPending ? 'Creating...' : 'Create Profile'}
-              </Button>
-            </div>
-          </form>
-        </Form>
-      </DialogContent>
-    </Dialog>
-  );
-}
-```
-
-### Phase 2: Generation (Week 2)
-
-#### GenerationForm Component
-
-**app/src/components/Generation/GenerationForm.tsx:**
-```typescript
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import * as z from 'zod';
-import {
-  Form,
-  FormControl,
-  FormDescription,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormMessage,
-} from '@/components/ui/form';
-import { Input } from '@/components/ui/input';
-import { Textarea } from '@/components/ui/textarea';
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import { Button } from '@/components/ui/button';
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Loader2 } from 'lucide-react';
-import { useGeneration } from '@/lib/hooks/useGeneration';
-import { useProfiles } from '@/lib/hooks/useProfiles';
-import { useToast } from '@/hooks/use-toast';
-
-const generationSchema = z.object({
-  profileId: z.string().min(1, 'Please select a voice profile'),
-  text: z.string().min(1, 'Text is required').max(5000),
-  language: z.enum(['en', 'zh']),
-  seed: z.number().int().optional(),
-});
-
-type GenerationFormValues = z.infer<typeof generationSchema>;
-
-export function GenerationForm() {
-  const { data: profiles } = useProfiles();
-  const generation = useGeneration();
-  const { toast } = useToast();
-
-  const form = useForm<GenerationFormValues>({
-    resolver: zodResolver(generationSchema),
-    defaultValues: {
-      profileId: '',
-      text: '',
-      language: 'en',
-      seed: undefined,
-    },
-  });
-
-  async function onSubmit(data: GenerationFormValues) {
-    try {
-      const result = await generation.mutateAsync({
-        profile_id: data.profileId,
-        text: data.text,
-        language: data.language,
-        seed: data.seed,
-      });
-
-      toast({
-        title: 'Generation complete!',
-        description: `Audio generated (${result.duration.toFixed(2)}s)`,
-      });
-
-      form.reset();
-    } catch (error) {
-      toast({
-        title: 'Generation failed',
-        description: error.message,
-        variant: 'destructive',
-      });
-    }
-  }
-
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Generate Speech</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <Form {...form}>
-          <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-            <FormField
-              control={form.control}
-              name="profileId"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Voice Profile</FormLabel>
-                  <Select
-                    onValueChange={field.onChange}
-                    defaultValue={field.value}
-                  >
-                    <FormControl>
-                      <SelectTrigger>
-                        <SelectValue placeholder="Select a voice" />
-                      </SelectTrigger>
-                    </FormControl>
-                    <SelectContent>
-                      {profiles?.map((profile) => (
-                        <SelectItem key={profile.id} value={profile.id}>
-                          {profile.name}
-                        </SelectItem>
-                      ))}
-                    </SelectContent>
-                  </Select>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="text"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Text to Speak</FormLabel>
-                  <FormControl>
-                    <Textarea
-                      placeholder="Enter the text you want to generate..."
-                      className="min-h-[200px]"
-                      {...field}
-                    />
-                  </FormControl>
-                  <FormDescription>
-                    Max 5000 characters
-                  </FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <div className="grid gap-4 md:grid-cols-2">
-              <FormField
-                control={form.control}
-                name="language"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Language</FormLabel>
-                    <Select
-                      onValueChange={field.onChange}
-                      defaultValue={field.value}
-                    >
-                      <FormControl>
-                        <SelectTrigger>
-                          <SelectValue />
-                        </SelectTrigger>
-                      </FormControl>
-                      <SelectContent>
-                        <SelectItem value="en">English</SelectItem>
-                        <SelectItem value="zh">Chinese</SelectItem>
-                      </SelectContent>
-                    </Select>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-
-              <FormField
-                control={form.control}
-                name="seed"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>Seed (optional)</FormLabel>
-                    <FormControl>
-                      <Input
-                        type="number"
-                        placeholder="Random"
-                        {...field}
-                        onChange={(e) =>
-                          field.onChange(
-                            e.target.value ? parseInt(e.target.value) : undefined
-                          )
-                        }
-                      />
-                    </FormControl>
-                    <FormDescription>
-                      For reproducible results
-                    </FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </div>
-
-            <Button
-              type="submit"
-              className="w-full"
-              disabled={generation.isPending}
-            >
-              {generation.isPending ? (
-                <>
-                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-                  Generating...
-                </>
-              ) : (
-                'Generate Speech'
-              )}
-            </Button>
-          </form>
-        </Form>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-### Phase 3: History (Week 2)
-
-#### HistoryTable Component
-
-**app/src/components/History/HistoryTable.tsx:**
-```typescript
-import { useState } from 'react';
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from '@/components/ui/table';
-import { Button } from '@/components/ui/button';
-import { Badge } from '@/components/ui/badge';
-import { Play, Download, Trash2 } from 'lucide-react';
-import { useHistory, useDeleteGeneration } from '@/lib/hooks/useHistory';
-import { formatDistance } from 'date-fns';
-
-export function HistoryTable() {
-  const [page, setPage] = useState(0);
-  const limit = 20;
-
-  const { data: history, isLoading } = useHistory({
-    limit,
-    offset: page * limit,
-  });
-
-  const deleteGeneration = useDeleteGeneration();
-
-  if (isLoading) {
-    return <div>Loading history...</div>;
-  }
-
-  return (
-    <div className="space-y-4">
-      <h2 className="text-2xl font-bold">Generation History</h2>
-
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Text</TableHead>
-            <TableHead>Profile</TableHead>
-            <TableHead>Language</TableHead>
-            <TableHead>Duration</TableHead>
-            <TableHead>Created</TableHead>
-            <TableHead className="text-right">Actions</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {history?.map((gen) => (
-            <TableRow key={gen.id}>
-              <TableCell className="max-w-[300px] truncate">
-                {gen.text}
-              </TableCell>
-              <TableCell>{gen.profile_name}</TableCell>
-              <TableCell>
-                <Badge variant="outline">{gen.language}</Badge>
-              </TableCell>
-              <TableCell>{gen.duration.toFixed(2)}s</TableCell>
-              <TableCell>
-                {formatDistance(new Date(gen.created_at), new Date(), {
-                  addSuffix: true,
-                })}
-              </TableCell>
-              <TableCell className="text-right">
-                <div className="flex justify-end gap-2">
-                  <Button variant="ghost" size="icon">
-                    <Play className="h-4 w-4" />
-                  </Button>
-                  <Button variant="ghost" size="icon">
-                    <Download className="h-4 w-4" />
-                  </Button>
-                  <Button
-                    variant="ghost"
-                    size="icon"
-                    onClick={() => deleteGeneration.mutate(gen.id)}
-                  >
-                    <Trash2 className="h-4 w-4 text-destructive" />
-                  </Button>
-                </div>
-              </TableCell>
-            </TableRow>
-          ))}
-        </TableBody>
-      </Table>
-
-      <div className="flex justify-between">
-        <Button
-          variant="outline"
-          onClick={() => setPage((p) => Math.max(0, p - 1))}
-          disabled={page === 0}
-        >
-          Previous
-        </Button>
-        <Button
-          variant="outline"
-          onClick={() => setPage((p) => p + 1)}
-          disabled={!history || history.length < limit}
-        >
-          Next
-        </Button>
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-## Implementation Phases
-
-### Phase 1: Foundation (Week 1)
-**Goal:** Setup, OpenAPI client, basic UI
-
-1. **Day 1-2: Setup**
-   - ✅ Install shadcn/ui and dependencies
-   - ✅ Generate OpenAPI client
-   - ✅ Setup providers (React Query, Toaster)
-   - ✅ Create Zustand stores
-   - ✅ Setup routing (if needed)
-
-2. **Day 3-4: Voice Profiles**
-   - ProfileList component
-   - ProfileCard component
-   - ProfileForm (create/edit)
-   - Profile deletion
-   - Sample upload UI
-
-3. **Day 5-7: Testing & Polish**
-   - Test all CRUD operations
-   - Error handling
-   - Loading states
-   - Empty states
-
-### Phase 2: Generation & History (Week 2)
-**Goal:** Core voice generation functionality
-
-1. **Day 1-3: Generation**
-   - GenerationForm component
-   - Real-time generation
-   - Progress indication
-   - Audio preview player
-   - Download functionality
-
-2. **Day 4-7: History**
-   - HistoryTable component
-   - Filtering and search
-   - Pagination
-   - Audio playback
-   - Export functionality
-
-### Phase 3: Audio Studio (Week 3-4)
-**Goal:** Timeline editing and advanced features
-
-1. **Week 3: Basic Studio**
-   - Waveform visualization (WaveSurfer.js)
-   - Timeline component
-   - Playback controls
-   - Multiple tracks
-
-2. **Week 4: Advanced Features**
-   - Word-level timestamps
-   - Editing (trim, split)
-   - Audio effects
-   - Project save/load
-
-### Phase 4: Polish & Features (Week 5+)
-**Goal:** Production polish
-
-1. **Server Settings**
-   - Connection management
-   - Local server toggle
-   - Health monitoring
-
-2. **UX Improvements**
-   - Keyboard shortcuts
-   - Drag and drop
-   - Batch operations
-   - Export options
-
----
-
-## Type Safety Best Practices
-
-### 1. OpenAPI Generated Types
-
-```typescript
-// Use generated types from @/lib/api/models
-import type {
-  VoiceProfileResponse,
-  GenerationRequest,
-  HistoryQuery,
-} from '@/lib/api/models';
-
-// Never use `any`
-function handleProfile(profile: VoiceProfileResponse) {
-  // Fully typed
-}
-```
-
-### 2. Zod Schemas Match Backend
-
-```typescript
-// app/src/lib/schemas/profile.ts
-import { z } from 'zod';
-
-// Match backend Pydantic model
-export const profileCreateSchema = z.object({
-  name: z.string().min(1).max(100),
-  description: z.string().optional(),
-  language: z.enum(['en', 'zh']),
-  tags: z.array(z.string()).optional(),
-});
-
-export type ProfileCreate = z.infer<typeof profileCreateSchema>;
-```
-
-### 3. React Hook Form with Zod
-
-```typescript
-const form = useForm<ProfileCreate>({
-  resolver: zodResolver(profileCreateSchema),
-});
-
-// Fully typed, runtime validated
-```
-
-### 4. Type-Safe Event Handlers
-
-```typescript
-// Good
-function handleSubmit(data: ProfileCreate) {
-  // data is typed
-}
-
-// Bad
-function handleSubmit(data: any) {
-  // No type safety
-}
-```
-
----
-
-## Performance Optimizations
-
-### 1. React Query Configuration
-
-```typescript
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // Don't refetch for 5 minutes
-      gcTime: 1000 * 60 * 10,    // Keep unused data for 10 minutes
-      retry: 1,                  // Only retry once
-    },
-  },
-});
-```
-
-### 2. Component Code Splitting
-
-```typescript
-import { lazy } from 'react';
-
-const AudioStudio = lazy(() => import('@/components/AudioStudio'));
-
-// Lazy load heavy components
-```
-
-### 3. Virtualized Lists
-
-For large history tables:
-```bash
-bunx --bun shadcn-ui@latest add table
-```
-
-Use with TanStack Virtual for performance.
-
-### 4. Debounced Search
-
-```typescript
-import { useDebouncedValue } from '@/hooks/useDebouncedValue';
-
-const [search, setSearch] = useState('');
-const debouncedSearch = useDebouncedValue(search, 300);
-
-// Use debouncedSearch in query
-useHistory({ search: debouncedSearch });
-```
-
----
-
-## Testing Strategy
-
-### Unit Tests (Vitest)
-
-```bash
-bun add -D vitest @testing-library/react @testing-library/jest-dom
-```
-
-**app/src/components/VoiceProfiles/ProfileCard.test.tsx:**
-```typescript
-import { describe, it, expect } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { ProfileCard } from './ProfileCard';
-
-describe('ProfileCard', () => {
-  it('renders profile name', () => {
-    render(<ProfileCard profile={{ name: 'Test Voice' }} />);
-    expect(screen.getByText('Test Voice')).toBeInTheDocument();
-  });
-});
-```
-
-### Component Tests (Storybook - Optional)
-
-```bash
-bunx storybook@latest init
-```
-
----
-
-## Accessibility
-
-shadcn/ui components are built on Radix UI with full accessibility:
-
-- ✅ Keyboard navigation
-- ✅ Screen reader support
-- ✅ ARIA attributes
-- ✅ Focus management
-
-**Additional improvements:**
-1. Add `aria-label` to icon buttons
-2. Use semantic HTML (`<main>`, `<nav>`, `<section>`)
-3. Ensure color contrast meets WCAG AA
-4. Add loading announcements for screen readers
-
----
-
-## Summary
-
-**Tech Stack:**
-- React 18 + TypeScript (strict)
-- shadcn/ui + Radix UI
-- React Query + Zustand
-- React Hook Form + Zod
-- Tailwind CSS v4
-- WaveSurfer.js
-
-**Type Safety:**
-- ✅ OpenAPI generated client
-- ✅ Zod runtime validation
-- ✅ TypeScript strict mode
-- ✅ No `any` types
-
-**Implementation:**
-- Phase 1: Voice Profiles (Week 1)
-- Phase 2: Generation & History (Week 2)
-- Phase 3: Audio Studio (Week 3-4)
-- Phase 4: Polish (Week 5+)
-
-**Next Steps:**
-1. Run `bunx --bun shadcn-ui@latest init`
-2. Generate OpenAPI client (`bun run generate:api`)
-3. Add essential shadcn/ui components
-4. Build ProfileList component
-5. Test with backend
-
-Ready to build a production-quality, type-safe voice cloning app! 🚀
diff --git a/docs/ICON_WORKFLOW.md b/docs/ICON_WORKFLOW.md
deleted file mode 100644
index d5b4f3e6..00000000
--- a/docs/ICON_WORKFLOW.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# Icon Update Workflow for voicebox
-
-## Prerequisites
-- Xcode Command Line Tools installed (`xcode-select --install`)
-- Your icon designed in Icon Composer and saved as `voicebox.icon` in the project root
-
-## Directory Structure
-```
-voicebox/
-├── voicebox.icon/              # macOS 26 Liquid Glass icon bundle
-│   ├── icon.json
-│   └── Assets/
-│       └── Voicebox.png        # Your source image
-├── tauri/
-│   ├── assets/
-│   │   └── voicebox_exports/   # Your 1024x1024 exports
-│   └── src-tauri/
-│       ├── gen/                # Auto-generated at build time
-│       │   ├── Assets.car      # Liquid Glass assets
-│       │   ├── voicebox.icns   # Generated fallback icon
-│       │   └── partial.plist
-│       └── icons/              # Tauri fallback icons (all platforms)
-│           ├── icon.icns
-│           ├── icon.ico
-│           ├── 32x32.png
-│           ├── 128x128.png
-│           └── ...
-```
-
-## Step 1: Update the Liquid Glass Icon
-
-Edit `voicebox.icon/` in Icon Composer (or manually update `icon.json` and `Assets/`).
-
-The build script (`build.rs`) automatically compiles this during `cargo build`.
-
-## Step 2: Regenerate Fallback Icons
-
-After updating the `.icon` bundle, regenerate the fallback icons:
-
-```bash
-cd tauri/src-tauri
-
-# Trigger rebuild to generate new icns
-cargo build
-
-# Copy the generated icns to icons folder
-cp gen/voicebox.icns icons/icon.icns
-
-# Generate PNGs from the icns
-sips -s format png -z 32 32 gen/voicebox.icns --out icons/32x32.png
-sips -s format png -z 64 64 gen/voicebox.icns --out icons/64x64.png
-sips -s format png -z 128 128 gen/voicebox.icns --out icons/128x128.png
-sips -s format png -z 256 256 gen/voicebox.icns --out icons/128x128@2x.png
-sips -s format png -z 512 512 gen/voicebox.icns --out icons/icon.png
-
-# Windows Square logos
-for size in 30 44 71 89 107 142 150 284 310; do
-  sips -s format png -z $size $size gen/voicebox.icns --out "icons/Square${size}x${size}Logo.png"
-done
-```
-
-## Step 3: Rebuild the App
-
-```bash
-cd tauri && bun run tauri build
-```
-
-## Step 4: Clear Icon Cache (if icons don't update)
-
-```bash
-sudo rm -rf /Library/Caches/com.apple.iconservices.store
-sudo killall Finder
-sudo killall Dock
-```
-
----
-
-## How It Works
-
-| File | Purpose |
-|------|---------|
-| `voicebox.icon/` | Source for macOS 26 Liquid Glass icon |
-| `build.rs` | Compiles `.icon` → `Assets.car` + `voicebox.icns` at build time |
-| `gen/Assets.car` | Liquid Glass assets (macOS 26+) |
-| `gen/voicebox.icns` | Auto-generated fallback icon |
-| `icons/icon.icns` | Tauri's fallback for older macOS |
-| `icons/*.png` | Tauri's fallback for other platforms |
-| `Info.plist` | Points to `voicebox` as icon name |
-| `tauri.conf.json` | Bundles `gen/*` to Resources root |
-
-## Key Config Files
-
-### `build.rs` — Compiles the icon
-
-```rust
-xcrun actool --app-icon voicebox ... voicebox.icon
-```
-
-### `tauri.conf.json` — Bundles generated assets to Resources root
-
-```json
-"resources": {
-  "gen/Assets.car": "./",
-  "gen/voicebox.icns": "./",
-  "gen/partial.plist": "./"
-}
-```
-
-### `Info.plist` — Tells macOS which icon to use
-
-```xml
-<key>CFBundleIconFile</key>
-<string>voicebox</string>
-<key>CFBundleIconName</key>
-<string>voicebox</string>
-```
-
-## Quick Reference Script
-
-Save this as `scripts/update-icons.sh`:
-
-```bash
-#!/bin/bash
-set -e
-
-cd "$(dirname "$0")/../tauri/src-tauri"
-
-echo "Building to generate new icons..."
-cargo build
-
-echo "Copying icns to icons folder..."
-cp gen/voicebox.icns icons/icon.icns
-
-echo "Generating PNG icons..."
-sips -s format png -z 32 32 gen/voicebox.icns --out icons/32x32.png
-sips -s format png -z 64 64 gen/voicebox.icns --out icons/64x64.png
-sips -s format png -z 128 128 gen/voicebox.icns --out icons/128x128.png
-sips -s format png -z 256 256 gen/voicebox.icns --out icons/128x128@2x.png
-sips -s format png -z 512 512 gen/voicebox.icns --out icons/icon.png
-
-echo "Generating Windows Square logos..."
-for size in 30 44 71 89 107 142 150 284 310; do
-  sips -s format png -z $size $size gen/voicebox.icns --out "icons/Square${size}x${size}Logo.png"
-done
-
-echo "Done! Icons updated."
-echo "Run 'bun run tauri build' to rebuild the app."
-```
-
-Make it executable: `chmod +x scripts/update-icons.sh`
diff --git a/docs/IMPLEMENTATION_STATUS.md b/docs/IMPLEMENTATION_STATUS.md
deleted file mode 100644
index 87b900ae..00000000
--- a/docs/IMPLEMENTATION_STATUS.md
+++ /dev/null
@@ -1,287 +0,0 @@
-# Backend Implementation Status
-
-## ✅ COMPLETE - Ready for Frontend Integration
-
-### What's Been Built
-
-The voicebox backend is **fully implemented** and production-ready with the following features:
-
-#### Core Modules (100% Complete)
-
-1. **TTS Module** (`tts.py`) - 200 lines
-   - Lazy model loading with device detection
-   - Voice prompt creation and caching
-   - Multi-reference combination
-   - Async generation with seed control
-   - Model size switching (1.7B/0.6B)
-   - Memory management
-
-2. **Profiles Module** (`profiles.py`) - 250 lines
-   - Full CRUD operations
-   - Multi-sample support
-   - Audio validation
-   - Automatic sample combination
-   - File storage management
-
-3. **History Module** (`history.py`) - 150 lines
-   - Generation tracking
-   - Search and filtering
-   - Pagination
-   - Statistics
-   - File cleanup
-
-4. **Transcribe Module** (`transcribe.py`) - 150 lines
-   - Whisper transcription
-   - Language hints
-   - Model size selection
-   - VRAM management
-
-5. **Database Module** (`database.py`) - 90 lines
-   - SQLite with SQLAlchemy
-   - Clean schema design
-   - Foreign keys
-   - UUID primary keys
-
-6. **Utils Module** - 300 lines total
-   - Audio processing (normalization, validation)
-   - Voice prompt caching (memory + disk)
-   - Input validation
-
-7. **API Module** (`main.py`) - 300 lines
-   - 20+ REST endpoints
-   - File upload handling
-   - File serving
-   - Health checks
-   - Model management
-
-### API Endpoints
-
-#### Implemented ✅
-- `GET /` - Root
-- `GET /health` - Health check
-- `POST /profiles` - Create profile
-- `GET /profiles` - List profiles
-- `GET /profiles/{id}` - Get profile
-- `PUT /profiles/{id}` - Update profile
-- `DELETE /profiles/{id}` - Delete profile
-- `POST /profiles/{id}/samples` - Add sample
-- `GET /profiles/{id}/samples` - List samples
-- `DELETE /profiles/samples/{id}` - Delete sample
-- `POST /generate` - Generate speech
-- `GET /history` - List history
-- `GET /history/{id}` - Get generation
-- `DELETE /history/{id}` - Delete generation
-- `GET /history/stats` - Statistics
-- `GET /audio/{id}` - Download audio
-- `POST /transcribe` - Transcribe audio
-- `POST /models/load` - Load model
-- `POST /models/unload` - Unload model
-
-#### Total: 20 endpoints, all tested and working
-
-### Testing
-
-```bash
-# 1. Start server
-cd backend
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-python main.py
-
-# 2. Run example
-python example_usage.py
-
-# 3. Test with curl
-curl http://localhost:8000/health
-```
-
-### Documentation
-
-- ✅ `README.md` - Complete API documentation
-- ✅ `IMPLEMENTATION_STATUS.md` - This file
-- ✅ `example_usage.py` - Example client code
-- ✅ `../docs/BACKEND_IMPLEMENTATION.md` - Implementation details
-- ✅ `../docs/COMPETITIVE_ANALYSIS.md` - Comparison with references
-
-### Code Quality
-
-- **Total lines:** ~1,500 (clean, maintainable)
-- **Largest file:** 300 lines (main.py)
-- **Type safety:** 100% (Pydantic + type hints)
-- **Async/await:** 100%
-- **Modularity:** Excellent (12 files)
-- **Error handling:** Comprehensive
-- **Documentation:** Complete
-
-### Next Steps for Integration
-
-1. **Frontend can now:**
-   - Create voice profiles
-   - Upload audio samples
-   - Generate speech
-   - View history
-   - Download audio files
-   - Transcribe audio
-
-2. **Frontend needs to:**
-   - Call REST API endpoints
-   - Handle file uploads
-   - Display UI for profiles/history
-   - Play audio files
-
-3. **Backend ready for:**
-   - Tauri integration
-   - Web deployment
-   - Docker containerization
-   - Production deployment
-
-### Future Enhancements (Not Blocking)
-
-#### Phase 2 (Next)
-- WebSocket streaming
-- Batch generation
-- Audio effects
-- Voice design
-- Unit tests
-
-#### Phase 3 (Later)
-- Audio studio
-- Word-level timestamps
-- Projects
-- Export options
-
-#### Phase 4 (Production)
-- Authentication
-- Rate limiting
-- Docker
-- CI/CD
-
-### Dependencies
-
-All dependencies in `requirements.txt`:
-```
-fastapi>=0.109.0
-uvicorn[standard]>=0.27.0
-pydantic>=2.5.0
-sqlalchemy>=2.0.0
-torch>=2.1.0
-transformers>=4.36.0
-librosa>=0.10.0
-soundfile>=0.12.0
-python-multipart>=0.0.6
-```
-
-### Performance
-
-- **First generation:** 6-10 seconds (creates prompt + generates)
-- **Cached generation:** 1-2 seconds (uses cached prompt)
-- **Model loading:** 3-5 seconds (one-time)
-- **Transcription:** 2-5 seconds (depends on audio length)
-
-### Architecture Benefits
-
-1. **Modular** - Easy to extend
-2. **Type-safe** - Catch errors early
-3. **Async** - Non-blocking operations
-4. **Cached** - Fast repeated generations
-5. **Persistent** - Database-backed
-6. **Clean** - Maintainable code
-7. **Documented** - Complete API docs
-
-### Comparison to References
-
-**voicebox is:**
-- ✅ More maintainable than Voice-Clone-Studio (no 2815-line files)
-- ✅ More feature-rich than Qwen3-TTS_server (20 vs 3 endpoints)
-- ✅ Better caching than mimic (voice prompts cached)
-- ✅ Better typed than all references (100% Pydantic)
-- ✅ Better organized than qwen3-tts-enhanced (12 files vs 1)
-
-### Status: READY FOR FRONTEND ✅
-
-The backend is **complete and production-ready** for:
-- ✅ Tauri desktop app integration
-- ✅ Web app deployment
-- ✅ API client generation (OpenAPI)
-- ✅ Real-world usage
-
-**No blockers remaining.** Frontend can begin integration immediately.
-
----
-
-## Quick Start for Frontend Developers
-
-### 1. Start Backend
-```bash
-cd backend
-python main.py
-```
-
-### 2. Test Connection
-```bash
-curl http://localhost:8000/health
-```
-
-### 3. Create Profile
-```bash
-curl -X POST http://localhost:8000/profiles \
-  -H "Content-Type: application/json" \
-  -d '{"name": "Test Voice", "language": "en"}'
-```
-
-### 4. Generate OpenAPI Client
-```bash
-# OpenAPI spec available at:
-http://localhost:8000/openapi.json
-
-# Use with openapi-typescript-codegen
-npx openapi-typescript-codegen \
-  --input http://localhost:8000/openapi.json \
-  --output ./src/lib/api \
-  --client fetch
-```
-
-### 5. Build Your UI
-```typescript
-import { ProfilesService, GenerateService } from '@/lib/api';
-
-// Create profile
-const profile = await ProfilesService.createProfile({
-  name: 'My Voice',
-  language: 'en',
-});
-
-// Generate speech
-const generation = await GenerateService.generateSpeech({
-  profile_id: profile.id,
-  text: 'Hello world',
-  language: 'en',
-});
-
-// Download audio
-const audioUrl = `/audio/${generation.id}`;
-```
-
----
-
-## Summary
-
-**Backend Status:** ✅ COMPLETE
-
-**Lines of Code:** ~1,500 (clean, maintainable)
-
-**Test Coverage:** Manual testing complete, unit tests TODO
-
-**Documentation:** 100% complete
-
-**Ready for:** Frontend integration, deployment, production
-
-**Next Steps:** Build Tauri frontend, integrate API
-
----
-
-**Questions?** See:
-- `README.md` for API documentation
-- `example_usage.py` for usage examples
-- `../docs/BACKEND_IMPLEMENTATION.md` for implementation details
diff --git a/docs/TAURI_PLAN.md b/docs/TAURI_PLAN.md
deleted file mode 100644
index 5fe12b6f..00000000
--- a/docs/TAURI_PLAN.md
+++ /dev/null
@@ -1,754 +0,0 @@
-# Tauri App Plan
-
-Plan for building voicebox as a Tauri 2.0 desktop app with shared frontend code for web deployment.
-
----
-
-## Project Structure
-
-```
-voicebox/
-├── app/                      # Shared React frontend (used by both web & desktop)
-│   ├── src/
-│   │   ├── components/
-│   │   │   ├── VoiceProfiles/
-│   │   │   ├── Generation/
-│   │   │   ├── AudioStudio/
-│   │   │   ├── History/
-│   │   │   └── ServerSettings/
-│   │   ├── lib/
-│   │   │   ├── api/          # Generated OpenAPI client
-│   │   │   ├── hooks/        # React Query hooks
-│   │   │   └── utils/
-│   │   ├── types/
-│   │   ├── App.tsx
-│   │   └── main.tsx
-│   ├── package.json
-│   ├── tsconfig.json
-│   ├── vite.config.ts
-│   └── tailwind.config.ts
-│
-├── tauri/                    # Tauri desktop app
-│   ├── src/                  # Thin wrapper, imports from ../app
-│   │   └── main.tsx          # Entry point that renders App from ../app
-│   ├── src-tauri/            # Rust backend
-│   │   ├── src/
-│   │   │   └── main.rs
-│   │   ├── icons/
-│   │   ├── binaries/         # Bundled Python server
-│   │   │   ├── voicebox-server-x86_64-apple-darwin
-│   │   │   ├── voicebox-server-aarch64-apple-darwin
-│   │   │   ├── voicebox-server-x86_64-unknown-linux-gnu
-│   │   │   └── voicebox-server-x86_64-pc-windows-msvc.exe
-│   │   ├── capabilities/
-│   │   │   └── default.json
-│   │   ├── Cargo.toml
-│   │   ├── Cargo.lock
-│   │   ├── tauri.conf.json
-│   │   └── build.rs
-│   ├── package.json
-│   └── vite.config.ts        # Points to ../app
-│
-├── web/                      # Web deployment
-│   ├── src/
-│   │   └── main.tsx          # Entry point that renders App from ../app
-│   ├── package.json
-│   └── vite.config.ts        # Points to ../app
-│
-├── backend/                  # Python FastAPI server
-│   ├── main.py
-│   ├── models.py
-│   ├── tts.py
-│   ├── transcribe.py
-│   ├── profiles.py
-│   ├── history.py
-│   ├── studio.py
-│   ├── database.py
-│   ├── utils/
-│   ├── requirements.txt
-│   └── build_binary.py       # PyInstaller build script
-│
-├── scripts/
-│   ├── build-server.sh       # Build Python server for all platforms
-│   └── generate-api.sh       # Generate OpenAPI client
-│
-├── package.json              # Root workspace config (Bun workspaces)
-└── bun.lockb                 # Bun lockfile
-```
-
----
-
-## Technology Stack
-
-### Desktop App (Tauri 2.0)
-- **Tauri 2.9.5+** - Latest stable version
-- **Rust** - Tauri backend
-- **React + TypeScript** - Frontend (shared with web)
-- **Vite** - Build tool
-- **Bun** - Fast package manager and JavaScript runtime
-
-### Shared Frontend
-- **React 18+** - UI framework
-- **TypeScript** - Type safety
-- **Vite** - Build tool and dev server
-- **Bun** - Package manager (faster than npm/yarn/pnpm)
-- **React Query** - Server state management
-- **Zustand** - Client state management
-- **Tailwind CSS** - Styling
-- **WaveSurfer.js** - Audio visualization
-
-### Backend Bundling
-- **PyInstaller** - Bundle Python server as standalone binary
-- **FastAPI** - Python web framework
-- **Tauri Sidecar** - Execute bundled Python server
-
----
-
-## Bundling Python Server with Tauri
-
-### 1. Build Python Server as Standalone Binary
-
-**Using PyInstaller:**
-```python
-# backend/build_binary.py
-import PyInstaller.__main__
-import sys
-import os
-
-def build_server():
-    PyInstaller.__main__.run([
-        'main.py',
-        '--onefile',
-        '--name', 'voicebox-server',
-        '--add-data', 'data:data',  # Include data files
-        '--hidden-import', 'torch',
-        '--hidden-import', 'transformers',
-        '--hidden-import', 'fastapi',
-        '--collect-all', 'qwen-tts',
-        '--noconfirm',
-    ])
-
-if __name__ == '__main__':
-    build_server()
-```
-
-**Build script for all platforms:**
-```bash
-#!/bin/bash
-# scripts/build-server.sh
-
-# Determine platform
-PLATFORM=$(rustc --print host-tuple)
-
-# Build Python binary
-cd backend
-python build_binary.py
-
-# Rename with platform triple
-cd dist
-mv voicebox-server ../src-tauri/binaries/voicebox-server-${PLATFORM}
-
-echo "Built voicebox-server-${PLATFORM}"
-```
-
-**Platform-specific binaries needed:**
-- macOS Intel: `voicebox-server-x86_64-apple-darwin`
-- macOS ARM: `voicebox-server-aarch64-apple-darwin`
-- Linux: `voicebox-server-x86_64-unknown-linux-gnu`
-- Windows: `voicebox-server-x86_64-pc-windows-msvc.exe`
-
-### 2. Configure Tauri to Bundle Binary
-
-**tauri/src-tauri/tauri.conf.json:**
-```json
-{
-  "bundle": {
-    "identifier": "sh.voicebox.app",
-    "externalBin": [
-      "binaries/voicebox-server"
-    ],
-    "resources": [
-      "binaries/*"
-    ]
-  },
-  "build": {
-    "beforeBuildCommand": "bun run build",
-    "devPath": "http://localhost:5173",
-    "distDir": "../dist"
-  }
-}
-```
-
-**Capabilities (src-tauri/capabilities/default.json):**
-```json
-{
-  "identifier": "default",
-  "description": "Default permissions",
-  "permissions": [
-    "core:default",
-    "shell:allow-execute",
-    "shell:allow-spawn",
-    "fs:default"
-  ]
-}
-```
-
-### 3. Launch Python Server from Tauri
-
-**tauri/src-tauri/src/main.rs:**
-```rust
-use tauri::{command, Manager};
-use tauri_plugin_shell::ShellExt;
-use std::sync::Mutex;
-
-struct ServerState {
-    child: Mutex<Option<tauri_plugin_shell::process::CommandChild>>,
-}
-
-#[command]
-async fn start_server(app: tauri::AppHandle, state: tauri::State<'_, ServerState>) -> Result<String, String> {
-    let sidecar = app.shell()
-        .sidecar("voicebox-server")
-        .map_err(|e| format!("Failed to get sidecar: {}", e))?;
-
-    let (mut rx, child) = sidecar
-        .spawn()
-        .map_err(|e| format!("Failed to spawn: {}", e))?;
-
-    // Store child process
-    *state.child.lock().unwrap() = Some(child);
-
-    // Wait for server to be ready (listen for startup log)
-    tokio::spawn(async move {
-        while let Some(event) = rx.recv().await {
-            if let tauri_plugin_shell::process::CommandEvent::Stdout(line) = event {
-                if String::from_utf8_lossy(&line).contains("Uvicorn running") {
-                    break;
-                }
-            }
-        }
-    });
-
-    Ok("Server started on http://localhost:8000".to_string())
-}
-
-#[command]
-async fn stop_server(state: tauri::State<'_, ServerState>) -> Result<(), String> {
-    if let Some(child) = state.child.lock().unwrap().take() {
-        child.kill().map_err(|e| format!("Failed to kill: {}", e))?;
-    }
-    Ok(())
-}
-
-#[cfg_attr(mobile, tauri::mobile_entry_point)]
-pub fn run() {
-    tauri::Builder::default()
-        .plugin(tauri_plugin_shell::init())
-        .manage(ServerState {
-            child: Mutex::new(None),
-        })
-        .invoke_handler(tauri::generate_handler![start_server, stop_server])
-        .run(tauri::generate_context!())
-        .expect("error while running tauri application");
-}
-```
-
-### 4. Call from Frontend
-
-**app/src/lib/hooks/useServer.ts:**
-```typescript
-import { invoke } from '@tauri-apps/api/core';
-import { useState } from 'react';
-
-export function useServer() {
-  const [serverUrl, setServerUrl] = useState<string>('http://localhost:8000');
-  const [isRunning, setIsRunning] = useState(false);
-
-  const startServer = async () => {
-    try {
-      const url = await invoke<string>('start_server');
-      setServerUrl(url);
-      setIsRunning(true);
-      return url;
-    } catch (error) {
-      console.error('Failed to start server:', error);
-      throw error;
-    }
-  };
-
-  const stopServer = async () => {
-    try {
-      await invoke('stop_server');
-      setIsRunning(false);
-    } catch (error) {
-      console.error('Failed to stop server:', error);
-      throw error;
-    }
-  };
-
-  return { serverUrl, isRunning, startServer, stopServer };
-}
-```
-
----
-
-## Shared Frontend Approach
-
-### App Package Structure
-
-The `app/` directory contains all React code that's shared between desktop and web.
-
-**app/vite.config.ts:**
-```typescript
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import path from 'path';
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
-    },
-  },
-  build: {
-    lib: {
-      entry: path.resolve(__dirname, 'src/main.tsx'),
-      formats: ['es'],
-    },
-    rollupOptions: {
-      external: ['react', 'react-dom'],
-    },
-  },
-});
-```
-
-### Tauri Wrapper
-
-**tauri/src/main.tsx:**
-```typescript
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from '../app/src/App';
-import '../app/src/index.css';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
-
-**tauri/vite.config.ts:**
-```typescript
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import path from 'path';
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, '../app/src'),
-    },
-  },
-  clearScreen: false,
-  server: {
-    port: 5173,
-    strictPort: true,
-  },
-  envPrefix: ['VITE_', 'TAURI_'],
-  build: {
-    target: 'es2021',
-    minify: !process.env.TAURI_DEBUG,
-    sourcemap: !!process.env.TAURI_DEBUG,
-    outDir: 'dist',
-  },
-});
-```
-
-**tauri/package.json:**
-```json
-{
-  "name": "@voicebox/tauri",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "tauri": "tauri"
-  },
-  "dependencies": {
-    "@tauri-apps/api": "^2.0.0",
-    "@tauri-apps/plugin-shell": "^2.0.0",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0"
-  },
-  "devDependencies": {
-    "@tauri-apps/cli": "^2.0.0",
-    "@vitejs/plugin-react": "^4.3.0",
-    "typescript": "^5.6.0",
-    "vite": "^5.4.0"
-  }
-}
-```
-
-### Web Wrapper
-
-**web/src/main.tsx:**
-```typescript
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from '../../app/src/App';
-import '../../app/src/index.css';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
-
-**web/vite.config.ts:**
-```typescript
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import path from 'path';
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, '../app/src'),
-    },
-  },
-  build: {
-    outDir: 'dist',
-  },
-});
-```
-
----
-
-## Development Workflow
-
-### 1. Initial Setup
-
-```bash
-# Install Bun (if not installed)
-curl -fsSL https://bun.sh/install | bash
-
-# Create Tauri app with official CLI
-cd voicebox
-bunx create-tauri-app tauri
-
-# Move app code to shared directory
-mkdir app
-# Move tauri/src/* to app/src/
-
-# Create web directory
-mkdir web
-cd web
-bunx create-vite . --template react-ts
-
-# Setup Bun workspace in root package.json
-cat > package.json << 'EOF'
-{
-  "name": "voicebox",
-  "private": true,
-  "workspaces": ["app", "tauri", "web"]
-}
-EOF
-
-# Install all dependencies
-bun install
-```
-
-### 2. Development
-
-**Terminal 1 - Backend (Python FastAPI):**
-```bash
-cd backend
-python -m venv venv
-source venv/bin/activate  # or venv\Scripts\activate on Windows
-pip install -r requirements.txt
-uvicorn main:app --reload --port 8000
-```
-
-**Terminal 2 - Frontend (Tauri dev mode):**
-```bash
-cd tauri
-bun run tauri dev
-```
-
-This will:
-1. Start Vite dev server on port 5173
-2. Launch Tauri window pointing to localhost:5173
-3. Hot reload on code changes
-
-**For web development:**
-```bash
-cd web
-bun run dev
-```
-
-### 3. Building for Production
-
-**Build Python server:**
-```bash
-./scripts/build-server.sh
-```
-
-**Build Tauri app:**
-```bash
-cd tauri
-bun run tauri build
-```
-
-This will:
-1. Build React frontend with Vite
-2. Bundle Python server binary
-3. Create platform-specific installers:
-   - macOS: `.app`, `.dmg`
-   - Windows: `.exe`, `.msi`
-   - Linux: `.deb`, `.AppImage`
-
-**Build web app:**
-```bash
-cd web
-bun run build
-```
-
----
-
-## Platform-Specific Considerations
-
-### macOS
-- Need both Intel and ARM builds
-- Sign and notarize for distribution outside App Store
-- Request permissions for microphone access (audio recording)
-
-**tauri.conf.json additions:**
-```json
-{
-  "bundle": {
-    "macOS": {
-      "minimumSystemVersion": "10.15",
-      "entitlements": "src-tauri/Entitlements.plist"
-    }
-  }
-}
-```
-
-**Entitlements.plist:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>com.apple.security.device.audio-input</key>
-    <true/>
-</dict>
-</plist>
-```
-
-### Windows
-- Build with NSIS or WiX installer
-- Consider code signing for SmartScreen
-
-### Linux
-- Provide multiple formats: .deb, .AppImage, .rpm
-- Consider Flatpak for broader distribution
-
----
-
-## OpenAPI Client Generation
-
-**scripts/generate-api.sh:**
-```bash
-#!/bin/bash
-
-# Start backend if not running
-if ! curl -s http://localhost:8000/openapi.json > /dev/null; then
-    echo "Starting backend..."
-    cd backend
-    uvicorn main:app --port 8000 &
-    BACKEND_PID=$!
-    sleep 5
-fi
-
-# Download OpenAPI schema
-curl http://localhost:8000/openapi.json > app/openapi.json
-
-# Generate TypeScript client
-cd app
-bunx openapi-typescript-codegen \
-    --input openapi.json \
-    --output src/lib/api \
-    --client fetch
-
-echo "API client generated in app/src/lib/api"
-
-# Kill backend if we started it
-if [ ! -z "$BACKEND_PID" ]; then
-    kill $BACKEND_PID
-fi
-```
-
-**Add to package.json:**
-```json
-{
-  "scripts": {
-    "generate:api": "./scripts/generate-api.sh"
-  }
-}
-```
-
----
-
-## Server Mode Architecture
-
-### Local Mode (Default)
-1. Tauri app starts
-2. App invokes `start_server` command
-3. Rust spawns bundled Python binary as sidecar
-4. Frontend connects to `http://localhost:8000`
-5. All features work locally
-
-### Remote Mode (One-Click)
-1. User clicks "Start Server" on GPU machine
-2. Tauri invokes `start_server` with `--host 0.0.0.0` flag
-3. Server displays connection URL (e.g., `http://192.168.1.100:8000`)
-4. User enters URL in client app
-5. Client connects to remote server
-6. All API calls go to remote machine
-
-**Rust command with args:**
-```rust
-#[command]
-async fn start_server(
-    app: tauri::AppHandle,
-    state: tauri::State<'_, ServerState>,
-    remote: bool,
-) -> Result<String, String> {
-    let mut sidecar = app.shell().sidecar("voicebox-server")
-        .map_err(|e| format!("Failed to get sidecar: {}", e))?;
-
-    if remote {
-        sidecar = sidecar.args(["--host", "0.0.0.0"]);
-    }
-
-    // ... rest of spawn logic
-}
-```
-
----
-
-## CI/CD for Multi-Platform Builds
-
-**GitHub Actions workflow:**
-```yaml
-name: Build
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  build:
-    strategy:
-      matrix:
-        platform: [macos-latest, ubuntu-latest, windows-latest]
-    runs-on: ${{ matrix.platform }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Setup Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Install dependencies
-        run: |
-          cd tauri
-          bun install
-
-      - name: Build Python server
-        run: |
-          cd backend
-          pip install -r requirements.txt
-          pip install pyinstaller
-          python build_binary.py
-
-      - name: Build Tauri app
-        uses: tauri-apps/tauri-action@v0
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          projectPath: tauri
-          tagName: v__VERSION__
-          releaseName: 'voicebox v__VERSION__'
-```
-
----
-
-## Key Decisions
-
-### Why This Structure?
-
-1. **Shared `app/` directory** - Single source of truth for UI code
-2. **Thin wrappers** - `tauri/` and `web/` just configure build tools
-3. **Sidecar pattern** - Bundle Python server without modifying Tauri core
-4. **PyInstaller** - Creates standalone Python binary with all dependencies
-5. **Platform-specific binaries** - Tauri automatically selects correct binary per platform
-
-### Benefits
-
-- ✅ No code duplication between web and desktop
-- ✅ Python server bundled - users don't install Python
-- ✅ Single command to build everything
-- ✅ Type-safe API calls via OpenAPI generation
-- ✅ Native performance with Tauri
-- ✅ Web fallback for unsupported platforms
-- ✅ Fast development with Bun (20-30x faster installs than npm)
-
-### Tradeoffs
-
-- ⚠️ Large bundle size (Python runtime + ML models + Tauri)
-- ⚠️ Need to build Python binary for each platform
-- ⚠️ First launch slow (model loading)
-- ⚠️ Separate web build doesn't include server (requires separate backend deployment)
-
----
-
-## Next Steps
-
-1. Set up monorepo structure
-2. Initialize Tauri app with `bunx create-tauri-app`
-3. Create shared `app/` directory
-4. Configure Vite to share code
-5. Build Python server with PyInstaller
-6. Configure Tauri sidecar
-7. Test on macOS, Windows, Linux
-8. Set up CI/CD for multi-platform builds
-
----
-
-## Resources
-
-- [Tauri 2.0 Documentation](https://v2.tauri.app/)
-- [Tauri Sidecar Guide](https://v2.tauri.app/develop/sidecar/)
-- [Bun Documentation](https://bun.sh/docs)
-- [Bun Workspaces](https://bun.sh/docs/install/workspaces)
-- [PyInstaller Documentation](https://pyinstaller.org/)
-- [React Query Documentation](https://tanstack.com/query/latest)
-- [OpenAPI TypeScript Codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 00000000..2b930db4
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,280 @@
+# Troubleshooting Guide
+
+Common issues and solutions for Voicebox.
+
+## Installation Issues
+
+### macOS: "Voicebox cannot be opened because it is from an unidentified developer"
+
+**Solution:**
+1. Right-click the `.dmg` file
+2. Select "Open"
+3. Click "Open" in the security dialog
+4. Alternatively, go to System Settings → Privacy & Security → Allow Voicebox
+
+### Windows: "Windows protected your PC"
+
+**Solution:**
+1. Click "More info"
+2. Click "Run anyway"
+3. Windows Defender may flag new software; this is normal for unsigned apps
+
+### Linux: AppImage won't run
+
+**Solution:**
+```bash
+chmod +x voicebox-*.AppImage
+./voicebox-*.AppImage
+```
+
+## Runtime Issues
+
+### Server won't start
+
+**Symptoms:** App opens but shows "Server not connected"
+
+**Solutions:**
+1. **Check Python installation**
+   ```bash
+   python --version  # Should be 3.11+
+   ```
+
+2. **Check server binary exists**
+   - Look in `tauri/src-tauri/binaries/` for your platform
+   - Binary should match your system architecture
+
+3. **Check permissions**
+   ```bash
+   # macOS/Linux
+   chmod +x tauri/src-tauri/binaries/voicebox-server-*
+   ```
+
+4. **Check logs**
+   - macOS: Open Console.app and search for "voicebox"
+   - Linux: Check `~/.local/share/voicebox/` for logs
+   - Windows: Check Event Viewer
+
+### "Model download failed"
+
+**Symptoms:** First generation fails with download error
+
+**Solutions:**
+1. **Check internet connection**
+   - Models download from HuggingFace Hub (~2-4GB)
+   - First download may take several minutes
+
+2. **Check disk space**
+   - Models are cached in `~/.cache/huggingface/`
+   - Ensure at least 5GB free space
+
+3. **Manual download** (if automatic fails)
+   ```bash
+   pip install huggingface_hub
+   huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base
+   ```
+
+### "Out of memory" errors
+
+**Symptoms:** Generation fails with CUDA/VRAM errors
+
+**Solutions:**
+1. **Use smaller model**
+   - Switch to 0.6B model instead of 1.7B
+   - Settings → Model Management → Load 0.6B
+
+2. **Close other applications**
+   - Free up GPU memory
+   - Close browser tabs, other ML apps
+
+3. **Use CPU mode**
+   - Slower but works without GPU
+   - Backend automatically falls back to CPU
+
+### Audio playback issues
+
+**Symptoms:** Generated audio won't play
+
+**Solutions:**
+1. **Check audio format**
+   - Audio is saved as WAV files
+   - Ensure your system supports WAV playback
+
+2. **Try downloading audio**
+   - Right-click → Download
+   - Play in external player
+
+3. **Check browser permissions** (web version)
+   - Allow audio autoplay in browser settings
+
+### Slow generation
+
+**Symptoms:** Generation takes >30 seconds
+
+**Solutions:**
+1. **Use GPU** (if available)
+   - Check Settings → Server Status
+   - Should show "GPU available: true"
+
+2. **Enable caching**
+   - Voice prompts are cached automatically
+   - Second generation with same voice should be faster
+
+3. **Use smaller model**
+   - 0.6B model is faster than 1.7B
+   - Quality difference is minimal for most voices
+
+4. **Check system resources**
+   - Close other CPU/GPU intensive apps
+   - Ensure adequate RAM (8GB+ recommended)
+
+## API Issues
+
+### "Connection refused" when using API
+
+**Solutions:**
+1. **Check server is running**
+   ```bash
+   curl http://localhost:8000/health
+   ```
+
+2. **Check remote mode**
+   - If connecting remotely, ensure server is started with `--host 0.0.0.0`
+   - Check firewall settings
+
+3. **Check port availability**
+   - Default port is 8000
+   - Ensure no other service is using it
+
+### CORS errors in browser
+
+**Solutions:**
+1. **Use desktop app** (recommended)
+   - Desktop app doesn't have CORS restrictions
+
+2. **Configure CORS** (for web deployment)
+   - Update `backend/main.py` CORS settings
+   - Add your domain to allowed origins
+
+## Update Issues
+
+### "Update check failed"
+
+**Solutions:**
+1. **Check internet connection**
+   - Updates are fetched from GitHub releases
+
+2. **Check GitHub access**
+   - Ensure `github.com` is accessible
+   - Check firewall/proxy settings
+
+3. **Manual update**
+   - Download latest release from GitHub
+   - Install manually
+
+### "Invalid signature" error
+
+**Solutions:**
+1. **Re-download installer**
+   - Signature may be corrupted
+   - Download fresh copy from GitHub
+
+2. **Check release integrity**
+   - Verify `.sig` file matches installer
+   - Report issue if signature is invalid
+
+## Data Issues
+
+### Profiles disappeared
+
+**Solutions:**
+1. **Check data directory**
+   - macOS: `~/Library/Application Support/voicebox/`
+   - Windows: `%APPDATA%/voicebox/`
+   - Linux: `~/.local/share/voicebox/`
+
+2. **Check database**
+   - Database: `data/voicebox.db`
+   - Ensure file exists and is readable
+
+3. **Restore from backup**
+   - Profiles can be exported/imported
+   - Check for backup files
+
+### "Database locked" error
+
+**Solutions:**
+1. **Close other instances**
+   - Ensure only one Voicebox instance is running
+
+2. **Restart app**
+   - Close and reopen Voicebox
+
+3. **Check file permissions**
+   - Ensure database file is writable
+   - Check directory permissions
+
+## Development Issues
+
+### Build fails
+
+**Solutions:**
+1. **Check Rust installation**
+   ```bash
+   rustc --version
+   rustup update
+   ```
+
+2. **Check Tauri dependencies**
+   ```bash
+   cd tauri
+   bun install
+   ```
+
+3. **Clean build**
+   ```bash
+   cd tauri/src-tauri
+   cargo clean
+   cd ../..
+   bun run build
+   ```
+
+### API client generation fails
+
+**Solutions:**
+1. **Start backend server**
+   ```bash
+   bun run dev:server
+   ```
+
+2. **Check OpenAPI endpoint**
+   ```bash
+   curl http://localhost:8000/openapi.json
+   ```
+
+3. **Regenerate client**
+   ```bash
+   bun run generate:api
+   ```
+
+## Still Having Issues?
+
+1. **Check existing issues**
+   - Search GitHub issues for similar problems
+   - Check closed issues for solutions
+
+2. **Create new issue**
+   - Include:
+     - OS and version
+     - Voicebox version
+     - Steps to reproduce
+     - Error messages/logs
+     - Screenshots (if applicable)
+
+3. **Get help**
+   - Check documentation in `docs/`
+   - Review `backend/README.md` for API details
+   - See `CONTRIBUTING.md` for development help
+
+---
+
+For more help, open an issue on [GitHub](https://github.com/jamiepine/voicebox/issues).