diff --git a/README.md b/README.md
index 8fd2702..76a3797 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,231 @@
-# challenge-pl
+# Challenge Platform - Frontend
 
+Фронтенд-приложение для системы проверки заданий через LLM (Challenge Service).
+
+## Описание
+
+Платформа позволяет студентам проходить цепочки заданий с автоматической проверкой через LLM, отслеживать прогресс и получать детальную обратную связь. Преподаватели имеют доступ к расширенной аналитике и панели администратора.
+
+## Возможности
+
+### Для студентов
+- ✅ Персональный dashboard с прогрессом и рекомендациями
+- ✅ Просмотр цепочек заданий и переход между задачами
+- ✅ Отправка решений с real-time отслеживанием проверки (polling)
+- ✅ Визуализация метрик: графики прогресса, timeline, heatmap активности
+- ✅ Экспорт статистики в CSV
+- ✅ Автосохранение черновиков решений (offline-режим)
+- ✅ Уведомления о результатах проверки
+
+### Для преподавателей (роль `teacher`)
+- ✅ Панель администратора с системной аналитикой
+- ✅ Метрики по заданиям: сложность, успешность, среднее время
+- ✅ Мониторинг очереди проверок
+- ✅ Выявление проблемных областей (длинная очередь, низкая успешность)
+- ✅ A/B тестирование вариантов интерфейса
+- ✅ Фильтрация заданий по сложности
+
+## Технологический стек
+
+- **React 18** + **TypeScript**
+- **Chakra UI 3** (компонентная библиотека)
+- **Redux Toolkit** + **RTK Query** (state management, API)
+- **React Router** (маршрутизация)
+- **Keycloak** (авторизация преподавателей)
+- **BroJS CLI** (инфраструктура сборки)
+
+## Структура проекта
+
+```
+src/
+├── __data__/
+│   ├── api/
+│   │   └── api.ts              # RTK Query эндпоинты
+│   ├── types.ts                # TypeScript типы
+│   ├── store.ts                # Redux store
+│   ├── urls.ts                 # URL-конфигурация
+│   └── kc.ts                   # Keycloak клиент
+├── components/
+│   ├── personal/               # Компоненты для студентов
+│   │   ├── PersonalDashboard.tsx
+│   │   ├── TaskWorkspace.tsx
+│   │   ├── StatCard.tsx
+│   │   ├── ProgressChart.tsx
+│   │   ├── TimelineChart.tsx
+│   │   ├── ActivityHeatmap.tsx
+│   │   ├── CheckStatusView.tsx
+│   │   ├── ResultView.tsx
+│   │   └── MobileDashboard.tsx
+│   └── admin/                  # Компоненты для преподавателей
+│       └── ABTestPanel.tsx
+├── context/
+│   └── ChallengeContext.tsx    # Контекст с кешем, polling, events
+├── hooks/
+│   └── useSubmission.ts        # Хук для отправки и отслеживания
+├── pages/
+│   ├── main/                   # Главная страница студента
+│   │   └── main.tsx
+│   └── admin/                  # Панель администратора
+│       └── AdminDashboard.tsx
+├── utils/
+│   ├── analytics/              # Метрики и аналитика
+│   │   └── index.ts
+│   ├── polling.ts              # Менеджер polling с exp. backoff
+│   ├── events.ts               # Event emitter
+│   ├── drafts.ts               # Работа с черновиками
+│   └── errors.ts               # Обработка ошибок
+├── app.tsx                     # Корневой компонент
+├── dashboard.tsx               # Роутинг
+├── index.tsx                   # Entry point
+└── theme.tsx                   # Chakra UI theme
+
+stubs/api/
+├── index.js                    # Express роутер для мок-данных
+└── data/                       # JSON-стабы всех эндпоинтов
+    ├── auth.json
+    ├── chains.json
+    ├── user-stats.json
+    ├── user-submissions.json
+    ├── system-stats.json
+    ├── submissions.json
+    ├── queue-status.json
+    └── submit.json
+```
+
+## Установка и запуск
+
+```bash
+# Установка зависимостей
+npm install
+
+# Запуск dev-сервера
+npm start
+
+# Сборка production
+npm run build:prod
+
+# Линтинг
+npm run eslint
+npm run eslint:fix
+```
+
+## API эндпоинты
+
+Приложение взаимодействует с Challenge Service API:
+
+- `POST /api/challenge/auth` — Аутентификация по nickname
+- `GET /api/challenge/chains` — Список цепочек заданий
+- `GET /api/challenge/chain/:id` — Детали цепочки
+- `GET /api/challenge/task/:id` — Детали задания
+- `POST /api/challenge/submit` — Отправка решения
+- `GET /api/challenge/check-status/:queueId` — Статус проверки (polling)
+- `GET /api/challenge/user/:id/stats` — Статистика пользователя
+- `GET /api/challenge/user/:id/submissions` — История отправок
+- `GET /api/challenge/stats` — Системная статистика (только teacher)
+- `GET /api/challenge/submissions` — Все отправки (только teacher)
+
+## Конфигурация
+
+Настройки задаются через `bro.config.js`:
+
+```javascript
+module.exports = {
+  config: {
+    journal: {
+      back: {
+        url: 'http://localhost:8082',
+      },
+    },
+  },
+  navigation: {
+    'challenge.main': '/',
+    'link.challenge.admin': '/admin',
+  },
+}
+```
+
+## Локальная разработка с моками
+
+Для работы без бэкенда используются стабы из `stubs/api`:
+
+```bash
+# Запустить мок-сервер (если есть отдельный порт)
+# или полагаться на brojs server, который использует stubs/api/index.js
+npm start
+```
+
+Мок-данные находятся в `stubs/api/data/*.json` и возвращаются Express-роутером.
+
+## Роли и доступ
+
+### Студенты (любой пользователь)
+- Доступ к главной странице (`/`)
+- Аутентификация через nickname (без пароля)
+- Просмотр своих заданий и статистики
+
+### Преподаватели (роль `teacher` в Keycloak)
+- Доступ к панели администратора (`/admin`)
+- Просмотр системных метрик и всех отправок
+- A/B тестирование
+- Аналитика по заданиям и пользователям
+
+Роль `teacher` должна быть назначена в Keycloak клиенте `journal`.
+
+## Основные функции
+
+### 1. ChallengeContext
+
+Глобальный контекст предоставляет:
+- Авторизацию пользователя (`login`, `logout`)
+- Статистику и персональный dashboard
+- Event emitter для уведомлений
+- Polling manager с экспоненциальной задержкой
+- Кеширование запросов (60 сек)
+- Сохранение/загрузка черновиков
+
+### 2. Polling механизм
+
+Автоматическое отслеживание статуса проверки:
+- Начальная задержка: 2 секунды
+- Экспоненциальный рост до 10 секунд
+- Автоматическая остановка при завершении
+
+### 3. Метрики
+
+Классы для сбора аналитики:
+- `MetricsCollector` — производительность проверок
+- `BehaviorTracker` — поведение пользователя (время, правки)
+- Функции построения dashboard и визуализаций
+
+### 4. Offline-режим
+
+- Автосохранение черновиков в localStorage
+- Индикатор офлайн-статуса
+- Возможность продолжить работу без сети
+
+## Типы данных
+
+Все TypeScript-интерфейсы описаны в `src/__data__/types.ts`:
+
+- `ChallengeUser`, `ChallengeTask`, `ChallengeChain`
+- `ChallengeSubmission`, `QueueStatus`
+- `UserStats`, `SystemStats`, `PersonalDashboard`
+- `PerformanceMetrics`, `BehaviorMetrics`, `SuccessMetrics`
+- Визуализация: `ProgressChartData`, `TimelineChartData`, `HeatmapData`
+- A/B тестирование: `ABTestMetrics`
+
+## Документация
+
+Подробная аналитика и руководства находятся в:
+- `memory bank/frontend/CHALLENGE_FRONTEND_GUIDE.md` — основное руководство
+- `memory bank/frontend/CHALLENGE_REACT_EXAMPLE.md` — примеры компонентов
+- `memory bank/frontend/CHALLENGE_ANALYTICS_SUMMARY.md` — метрики и дашборды
+- `memory bank/frontend/TEACHER_GUIDE.md` — для преподавателей
+
+## Лицензия
+
+ISC
+
+## Версия
+
+0.0.0 (в разработке)