diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a051b08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,195 @@
+# Smoke Tracker
+
+Веб-приложение для отслеживания привычки курения с визуализацией статистики.
+
+## 📋 Описание
+
+Smoke Tracker - это приложение для самоконтроля и отслеживания количества выкуренных сигарет. Позволяет вести учет, просматривать статистику по дням и анализировать динамику изменения привычки.
+
+## ✨ Возможности
+
+- **Регистрация и авторизация** - безопасная система входа с JWT токенами
+- **Учет сигарет** - быстрое добавление записей о выкуренных сигаретах
+- **История** - просмотр последних записей с возможностью фильтрации
+- **Статистика** - визуализация данных по дням с помощью графиков
+- **Адаптивный дизайн** - работает на всех устройствах
+
+## 🛠 Технологии
+
+### Frontend
+- **React 18** - библиотека для построения UI
+- **TypeScript** - типизированный JavaScript
+- **Chakra UI v3** - компонентная библиотека
+- **React Router v6** - маршрутизация
+- **React Hook Form** - управление формами
+- **Zod** - валидация схем
+- **Recharts** - графики и визуализация
+- **Axios** - HTTP клиент
+- **date-fns** - работа с датами
+
+### Backend (для локальной разработки)
+- **Express.js** - API stubs
+- **In-memory storage** - хранение данных в памяти
+
+### Build Tools
+- **Bro.js CLI** - конфигурация и сборка
+
+## 🚀 Быстрый старт
+
+### Установка зависимостей
+
+```bash
+npm install
+```
+
+### Запуск в режиме разработки
+
+```bash
+npm start
+```
+
+Приложение будет доступно по адресу, указанному в конфигурации Bro.js.
+
+### Сборка для продакшена
+
+```bash
+npm run build
+```
+
+## ⚙️ Конфигурация
+
+### API Endpoints
+
+Конфигурация API определяется в `bro.config.js`:
+
+```javascript
+config['smoke-tracker.api'] = './stubs/api/index.js' // для локальной разработки
+// или
+config['smoke-tracker.api'] = 'https://api.example.com' // для продакшена
+```
+
+### Локальная разработка
+
+Для локальной разработки используются API stubs в `./stubs/api/index.js`. Данные хранятся в памяти и сбрасываются при перезапуске сервера.
+
+### Стейджинг/Продакшн
+
+На стейджинге и продакшене значение конфигурации должно указывать на реальный backend API.
+
+## 📁 Структура проекта
+
+```
+smoke-tracker/
+├── src/
+│   ├── __data__/          # Константы и конфигурация
+│   │   └── urls.ts        # Маршруты приложения
+│   ├── api/               # API клиент
+│   │   └── client.ts      # Axios instance с interceptors
+│   ├── components/        # Переиспользуемые компоненты
+│   │   ├── ui/            # UI компоненты
+│   │   │   └── field.tsx  # Custom Field component
+│   │   └── ProtectedRoute.tsx
+│   ├── contexts/          # React Context
+│   │   └── AuthContext.tsx
+│   ├── pages/             # Страницы приложения
+│   │   ├── auth/          # Авторизация
+│   │   │   ├── signin.tsx
+│   │   │   └── signup.tsx
+│   │   ├── main/          # Главная страница
+│   │   ├── tracker/       # Страница учета
+│   │   └── stats/         # Страница статистики
+│   ├── types/             # TypeScript типы
+│   │   └── api.ts         # API типы
+│   ├── app.tsx            # Корневой компонент
+│   ├── dashboard.tsx      # Роутинг
+│   └── index.tsx          # Entry point
+├── stubs/
+│   └── api/
+│       └── index.js       # Mock API для разработки
+├── memory-bank/
+│   └── API.md             # Документация API
+├── bro.config.js          # Конфигурация Bro.js
+└── package.json
+```
+
+## 🔐 Авторизация
+
+Приложение использует JWT токены для авторизации:
+
+1. При входе/регистрации токен сохраняется в `localStorage`
+2. Токен автоматически добавляется во все API запросы через Axios interceptor
+3. При истечении токена пользователь перенаправляется на страницу входа
+4. Защищенные маршруты доступны только авторизованным пользователям
+
+### Тестовые данные для локальной разработки
+
+Создайте пользователя через форму регистрации или используйте API напрямую.
+
+Минимальные требования:
+- Логин: минимум 3 символа
+- Пароль: минимум 4 символа
+
+## 📊 API
+
+Полная документация API доступна в файле [`memory-bank/API.md`](./memory-bank/API.md).
+
+### Основные endpoints:
+
+- `POST /auth/signup` - Регистрация
+- `POST /auth/signin` - Вход
+- `POST /cigarettes/log` - Добавить запись о сигарете
+- `GET /cigarettes` - Получить список записей
+- `GET /cigarettes/stats/daily` - Получить статистику по дням
+
+## 🎨 UI/UX
+
+### Макеты страниц
+
+#### Страницы авторизации
+- Отдельный чистый layout
+- Центрированная форма
+- Без header/sidebar
+- Валидация в реальном времени
+- Информативные сообщения об ошибках
+
+#### Основные страницы
+- Header с информацией о пользователе
+- Навигация между разделами
+- Адаптивный grid layout
+
+#### Страница учета
+- Быстрая форма добавления записи
+- Список последних записей
+- Фильтрация по датам
+
+#### Страница статистики
+- Интерактивный график (Recharts)
+- Выбор периода
+- Сводная статистика
+
+## 🧪 Разработка
+
+### Добавление новых API endpoints
+
+1. Добавьте типы в `src/types/api.ts`
+2. Добавьте метод в `src/api/client.ts`
+3. Обновите mock в `stubs/api/index.js`
+
+### Добавление новых страниц
+
+1. Создайте компонент в `src/pages/`
+2. Добавьте маршрут в `src/__data__/urls.ts`
+3. Обновите роутинг в `src/dashboard.tsx`
+
+## 📝 Лицензия
+
+MIT
+
+## 👥 Автор
+
+Alex
+
+---
+
+**Примечание**: Это приложение создано для образовательных целей и самоконтроля. Курение вредит вашему здоровью.
+