diff --git a/.gitignore b/.gitignore
index 3e34afe..02acb11 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,9 +17,10 @@ frontend/dist/
 .env.local
 .env.production
 
-# IDE
+# IDE / tooling
 .idea/
 .vscode/
+.claude/
 *.swp
 *.swo
 
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c5478b8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# Personal AI Assistant
+
+A client-server web application for managing personal health and life areas with AI-powered assistance. Upload documents, chat with AI specialists, receive proactive health reminders, and track critical information across multiple life domains.
+
+## Key Features
+
+- **AI Chat with Specialists** — create chats using configurable skills (e.g., cardiologist, nutritionist). Each skill shapes the AI's behavior as a domain expert.
+- **Document Management** — upload health records, lab results, prescriptions, and consultation notes. AI extracts and indexes content for intelligent retrieval.
+- **Proactive Notifications** — AI analyzes your health profile and schedules reminders (checkups, medication reviews) via in-app, email, or Telegram.
+- **PDF Compilation** — request AI-generated health summaries as downloadable PDF documents.
+- **Global Memory** — AI maintains a shared memory of critical health information across all your chats.
+- **Multi-language** — English and Russian support.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Backend | Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic |
+| Frontend | React 18, TypeScript, Vite, Shadcn/ui, Tailwind CSS |
+| Database | PostgreSQL 16 |
+| AI | Claude API (Anthropic) |
+| Notifications | WebSocket, Email (SMTP), Telegram Bot |
+| Deployment | Docker Compose |
+
+## Getting Started
+
+> **Prerequisites**: Docker and Docker Compose installed.
+
+```bash
+# Clone the repository
+git clone https://git.dolgolyov-family.by/alexei.dolgolyov/personal-ai-assistant.git
+cd personal-ai-assistant
+
+# Copy environment config
+cp .env.example .env
+# Edit .env with your API keys and settings
+
+# Start all services
+docker compose up -d
+
+# Create initial admin user
+docker compose exec backend python scripts/seed_admin.py
+```
+
+The app will be available at `http://localhost`.
+
+## Project Structure
+
+```
+personal-ai-assistant/
+├── backend/          # FastAPI application
+├── frontend/         # React SPA
+├── telegram-bot/     # Telegram notification bot
+├── nginx/            # Reverse proxy config
+├── plans/            # Phase subplans
+├── docker-compose.yml
+└── GeneralPlan.md    # Full implementation plan
+```
+
+## License
+
+Private project. All rights reserved.