diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..6cc2b36
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+*.env
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+*.log
+logs/
+
+# OS
+.DS_Store
+Thumbs.db
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..be01e58
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MoAI (Master of AIs) is a multi-AI collaborative brainstorming platform. Multiple AI models (Claude, GPT, Gemini) discuss topics together in structured rounds, working toward consensus. Phase 1 is a Telegram bot; Phase 2 adds a web UI.
+
+## Build & Development Commands
+
+```bash
+# Install dependencies (use uv or pip)
+uv sync                          # or: pip install -e ".[dev]"
+
+# Run the bot
+python -m moai.bot.main
+
+# Run tests
+pytest                           # all tests
+pytest tests/test_models.py      # single file
+pytest -k "test_create"          # by name pattern
+pytest --cov=moai --cov-report=term-missing  # with coverage
+
+# Linting & formatting
+ruff check src tests             # lint
+ruff format src tests            # format
+ruff check --fix src tests       # auto-fix
+```
+
+## Architecture
+
+**Core flow:** Telegram command → Handler → Service → AI Orchestrator → Requesty/OpenRouter → Multiple AI APIs
+
+```
+src/moai/
+├── bot/
+│   ├── main.py           # Bot entry point, dispatcher setup
+│   ├── handlers/         # Telegram command handlers (thin, delegate to core)
+│   │   ├── projects.py   # /project commands
+│   │   ├── discussion.py # /open, /discuss, @mentions
+│   │   └── export.py     # /export, /consensus
+│   └── middleware.py     # Auth, logging
+└── core/
+    ├── models.py         # SQLAlchemy models (Project, Discussion, Round, Message, Consensus)
+    ├── database.py       # DB session management
+    ├── orchestrator.py   # AI round management, context building, consensus detection
+    ├── ai_client.py      # Requesty/OpenRouter wrapper, model routing
+    └── exporter.py       # Markdown generation
+```
+
+**Key patterns:**
+- Bot handlers are thin clients—business logic lives in `core/`
+- Orchestrator manages discussion state: parallel (open) vs sequential (discuss) modes
+- All AI calls go through `ai_client.py` which abstracts the routing layer
+- SQLite for Phase 1, models designed for PostgreSQL upgrade
+
+## Coding Standards
+
+- **Python 3.11+**
+- **Formatting:** ruff (line length 100)
+- **Type hints:** Required on all public functions
+- **Docstrings:** Required on modules and classes
+- **Logging:** Use `logging` module, no `print()`
+- **Testing:** pytest, target 80%+ coverage on core logic
+- **Dependencies:** No pinned versions unless security required
+
+## Data Model Relationships
+
+```
+Project (has many) → Discussion (has many) → Round (has many) → Message
+                   ↘ Discussion (has one) → Consensus
+```
+
+## Current Phase
+
+Phase 1: Telegram POC. Milestones:
+- M1: Bot responds to /help, /status
+- M2: Project CRUD
+- M3-M8: Discussion modes, consensus, export, @mentions