chore: add production deployment config and upgrade path requirements

- Add docker-compose.yml and docker-compose.example.yml for production deployment
- Add .env.example with all required environment variables
- Update architect agent with upgrade path requirements
- Update developer agent with migration best practices
- Add Phase 3 design documents (v0.3.0)
- Add ADR-0006 for participant state management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude/agents/developer.md

@@ -26,6 +26,55 @@ You implement features based on designs provided by the architect. You write pro
 4. **Stop on errors**: When you encounter failing tests, design inconsistencies, or blockers, stop and report to the coordinator immediately
 5. **Clean code**: Follow Python best practices and PEP standards
 6. **Mandatory docstrings**: All modules, classes, and functions must have docstrings
+7. **Clean upgrade paths**: All changes must support existing production installations
+
+## Upgrade Path Requirements
+
+**CRITICAL**: Sneaky Klaus is deployed in production with real user data. All changes must:
+
+1. **Preserve existing data**: Never lose exchanges, participants, or settings
+2. **Use Alembic migrations**: All database schema changes MUST use Alembic
+3. **Be reversible**: Migrations must have working `downgrade()` functions
+4. **Handle existing data**: New columns must have defaults or be nullable
+
+### Database Migration Rules
+
+```bash
+# NEVER use db.create_all() for schema changes
+# ALWAYS create migrations with:
+uv run alembic revision --autogenerate -m "description of change"
+
+# Review generated migration before committing
+# Ensure both upgrade() and downgrade() work correctly
+
+# Test migration on a copy of production data if possible
+```
+
+### Migration Best Practices
+
+1. **New columns on existing tables**:
+   - Must be nullable OR have a server_default
+   - Example: `sa.Column('new_field', sa.String(100), nullable=True)`
+
+2. **Renaming columns**:
+   - Use `op.alter_column()` with proper data preservation
+   - Never drop and recreate
+
+3. **Changing column types**:
+   - Create new column, migrate data, drop old column
+   - Or use `op.alter_column()` if type is compatible
+
+4. **Adding constraints**:
+   - Ensure existing data satisfies the constraint
+   - May need data cleanup migration first
+
+### Testing Migrations
+
+Before merging, verify:
+- [ ] Migration applies cleanly to fresh database
+- [ ] Migration applies cleanly to database with existing data
+- [ ] Downgrade works correctly
+- [ ] Application functions correctly after migration
 
 ## Code Style & Standards