From 1b55df508ce67d7ab80f31066ca7e90408032e5e Mon Sep 17 00:00:00 2001
From: Mikkel Georgsen <msgeorgsen@gmail.com>
Date: Fri, 16 Jan 2026 14:42:47 +0000
Subject: [PATCH] Add README.md with project overview

Visual documentation optimized for Forgejo with ASCII diagrams,
feature table, command reference, architecture overview, and roadmap.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bad5c0b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,166 @@
+<h1 align="center">
+  🗿 MoAI
+</h1>
+
+<p align="center">
+  <strong>Master of AIs</strong><br>
+  <em>Multi-model AI roundtable for collaborative brainstorming</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/status-Phase%201-orange?style=flat-square" alt="Status: Phase 1">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License: MIT">
+</p>
+
+---
+
+## 💡 The Idea
+
+Instead of asking **one** AI a question, ask a **team** of AIs.
+
+```
+You: "How should we architect our new microservice?"
+
+┌─────────┐  ┌─────────┐  ┌─────────┐
+│ Claude  │  │   GPT   │  │ Gemini  │
+└────┬────┘  └────┬────┘  └────┬────┘
+     │            │            │
+     ▼            ▼            ▼
+   "Event       "Start      "Consider
+   sourcing     simple,     the team's
+   gives you    monolith    experience
+   audit        first..."   level..."
+   trails..."
+     │            │            │
+     └────────────┼────────────┘
+                  ▼
+         🤝 Discussion Rounds
+                  ▼
+         📋 Consensus Summary
+```
+
+Models see each other's responses, debate, agree, disagree, and build upon ideas. You get richer, more diverse insights—then export everything as clean markdown.
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔀 **Open Mode** | Ask all models in parallel—get diverse initial takes |
+| 💬 **Discuss Mode** | Sequential rounds where models respond to each other |
+| 🎯 **@Mentions** | Direct questions to specific models: `@claude explain more` |
+| 🤝 **Consensus** | Auto-generated summary of agreements & disagreements |
+| 📁 **Projects** | Organize discussions by topic with persistent context |
+| 📤 **Export** | Beautiful markdown documents of entire discussions |
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Clone & setup
+git clone https://git.example.com/mikkel/moai.git
+cd moai
+uv sync  # or: pip install -e ".[dev]"
+
+# Configure
+cp .env.example .env
+# Edit .env with your tokens
+
+# Run
+python -m moai.bot.main
+```
+
+---
+
+## 🤖 Telegram Commands
+
+### Projects
+```
+/projects              List all projects
+/project new "Name"    Create project
+/project select <id>   Switch project
+/project models claude,gpt,gemini
+```
+
+### Discussion
+```
+/open <question>       Ask all models (parallel)
+/discuss [rounds]      Start discussion (default: 3 rounds)
+@claude <message>      Direct message to Claude
+@gpt <message>         Direct message to GPT
+/stop                  End current discussion
+```
+
+### Output
+```
+/consensus             Generate agreement summary
+/export                Export as markdown
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+┌──────────────────┐     ┌──────────────────────────────────┐
+│  Telegram Bot    │────▶│         Python Backend           │
+│  (thin client)   │     │                                  │
+└──────────────────┘     │  ┌────────────┐ ┌─────────────┐  │
+                         │  │ Handlers   │ │ Orchestrator│  │
+                         │  └─────┬──────┘ └──────┬──────┘  │
+                         │        │               │         │
+                         │        ▼               ▼         │
+                         │  ┌──────────┐   ┌───────────┐   │
+                         │  │ SQLite   │   │ AI Client │   │
+                         │  └──────────┘   └─────┬─────┘   │
+                         └───────────────────────┼─────────┘
+                                                 │
+                         ┌───────────────────────┼─────────┐
+                         │     Requesty / OpenRouter       │
+                         │  ┌─────────┬─────────┬────────┐ │
+                         │  │ Claude  │   GPT   │ Gemini │ │
+                         │  └─────────┴─────────┴────────┘ │
+                         └─────────────────────────────────┘
+```
+
+---
+
+## 📍 Roadmap
+
+- [x] **M1** Bot basics (`/help`, `/status`)
+- [ ] **M2** Project CRUD
+- [ ] **M3** Single model Q&A
+- [ ] **M4** Open mode (parallel)
+- [ ] **M5** Discuss mode (sequential)
+- [ ] **M6** Consensus generation
+- [ ] **M7** Markdown export
+- [ ] **M8** @mention support
+- [ ] **Phase 2** Web UI
+
+---
+
+## 🛠️ Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Bot | `python-telegram-bot` (async) |
+| Backend | Python 3.11+, FastAPI |
+| Database | SQLite → PostgreSQL |
+| AI Routing | Requesty / OpenRouter |
+| Linting | Ruff |
+| Testing | pytest |
+
+---
+
+## 📄 License
+
+MIT © 2026
+
+---
+
+<p align="center">
+  <sub>Why ask one AI when you can ask them all? 🗿</sub>
+</p>