diff --git a/AGENTS.md b/AGENTS.md
index 45d58e6..f071ffc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,164 +1,41 @@
 # AGENTS.md
 
-Инструкции для работы с репозиторием мини‑демо хранилища кликстрима.
+Короткий контракт для работы в репозитории мини-демо DWH кликстрима.
 
 ## Цель репозитория
 
-Решение [тестового задания DE](./data/DE-task.md) — развернуть в `docker compose` минимальный аналитический стек для обработки кликстрима e-commerce:
+Реализовать [тестовое задание DE](./docs/DE-task.md): поднять в `docker compose` стек Kafka + ClickHouse + Airflow + Superset + Prometheus/Grafana и получить витрины для первичного анализа.
 
-**Задача:** Подготовить данные для первичного анализа и собрать дашборд, на котором бизнес может сделать выводы.
+## Обязательные правила
 
-**Итоговый стек:**
+### Данные
 
-- Kafka (источник событий, 1 JSON message = 1 event)
-- ClickHouse (STG → ODS → DDS → DM)
-- **Airflow** (оркестрация ETL-пайплайна)
-- Superset (BI поверх витрин)
-- Prometheus + Grafana (мониторинг)
-- простой инструмент/скрипт, который читает `.jsonl` и пишет события в Kafka
+- Не загружать `*.jsonl` целиком без необходимости: по умолчанию использовать малый срез (`head -n 20..50`).
+- Для демо и тестов важнее быстрый и повторяемый прогон, чем полнота данных.
+- "Грязные" записи не должны валить пайплайн: ошибки парсинга фиксируются в ODS.
 
-## Ключевые артефакты
+### Изменения в коде
 
-### Исполняемые файлы (текущая структура)
-- `airflow/dags/` — Airflow DAGs для оркестрации ETL:
-  - `airflow/dags/ddl_init_dag.py` — инициализация схемы ClickHouse
-  - `airflow/dags/etl_pipeline_dag.py` — ETL процесс STG → ODS → DDS → DM
-  - `airflow/dags/kafka_load_dag.py` — загрузка данных в Kafka из JSONL
-  - `airflow/dags/utils/kafka_helpers.py` — helper-функции для работы с Kafka
-- `sql/` — SQL по слоям:
-  - `sql/ddl/00_databases.sql` — создание БД stg/ods/dds/dm
-  - `sql/ddl/stg/10_stg.sql` — STG слой (Kafka Engine + MV)
-  - `sql/ddl/ods/20_ods.sql` — ODS слой (типизация + MV для ошибок)
-  - `sql/ddl/dds/30_dds.sql` — DDS слой (таблицы для batch-загрузки)
-  - `sql/ddl/dm/40_dm.sql` — DM слой (витрины VIEW)
-  - `sql/dds/30_ods_to_dds.sql` — ODS → DDS (argMax + JOIN)
-  - `sql/dm/40_dds_to_dm.sql` — обновление DQ_summary
-- `scripts/` — скрипты автоматизации:
-  - `apply_clickhouse_ddl.sh` — применение DDL
-  - `load_kafka_data.sh` — загрузка в Kafka
-  - `run_batch.sh` — запуск batch-процесса
-- `airflow/` — конфигурация Airflow:
-  - `requirements.txt` — зависимости Airflow/ClickHouse plugin
+- Изменения держать минимальными и в скоупе задания (инфра, ingest, трансформации, витрины, мониторинг).
+- Не коммитить секреты. Использовать `.env` и `.env.example`.
+- При изменении инфраструктуры или DDL обновлять документацию в этом же PR.
+- Комментарии в SQL и Bash писать на русском языке.
 
-### Планы и документация (legacy)
-- `plans/clickhouse_ddl.md` — исходный план (inline DDL, legacy)
-- `plans/runbook.md` — runbook
-- `plans/kafka_ingest_plan.md` — план загрузки в Kafka
-- `docs/ARCHITECTURE.md` — подробное описание архитектуры
-- `data/DE-task.md` — текст задания.
-- `data/*.jsonl` — исходные данные (могут быть грязными).
-- `configs/` — конфиги ClickHouse/Prometheus/Grafana.
+### Проверка API через MCP Context7 (обязательно)
 
-## Правила по данным (важно)
+- Для спорных или меняющихся API (особенно Airflow/operators/providers) сначала уточнять актуальную версию через MCP Context7.
+- Минимальный порядок: `resolve-library-id` -> `query-docs`.
+- Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).
 
-- Не загружать исходные `*.jsonl` целиком: используйте `head -n 20..50`.
-- Для тестов/демо предпочтительнее “малый срез”, чем “идеальная полнота”.
-- Данные могут быть с ошибками — пайплайн должен быть устойчивым (в ODS фиксировать ошибки парсинга, а не падать).
+## Навигация по документации
 
-## Как запускать (локально)
+- [README.md](./README.md) — пользовательский quick start и обзор.
+- [docs/REPO_MAP.md](./docs/REPO_MAP.md) — карта исполняемых артефактов и где что менять.
+- [docs/OPERATIONS.md](./docs/OPERATIONS.md) — запуск, DAG-параметры, проверки и troubleshooting.
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — детали по слоям STG/ODS/DDS/DM.
+- [docs/COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов.
+- [plans/](./plans/) — legacy-планы (использовать как исторический контекст, не как источник истины).
 
-Базовые команды:
+## Ограничения по структуре
 
-- `make up` (или `docker compose up -d`)
-- `make ddl` (применяет SQL из `sql/ddl/00_databases.sql` и `sql/ddl/*/*.sql` в ClickHouse)
-- `make data` (пересоздаёт топики и заливает небольшой срез данных в Kafka; полный режим — `FULL=1 make data`)
-- `make transform` (запускает batch-процесс ODS → DDS → DM)
-- `docker compose up -d`
-- `docker compose ps`
-- `docker compose logs -f --tail=200 <service>`
-- `docker compose down` (сохраняет named volumes, включая `clickhouse-data`)
-- `docker compose down -v` (удалит volumes; используйте осознанно)
-
-Порты (см. `docker-compose.yml`):
-
-- ClickHouse native: `localhost:8002`
-- ClickHouse HTTP: `localhost:9123`
-- Kafka: `localhost:9092`
-- Kafka UI: `http://localhost:8082`
-- **Airflow: `http://localhost:8080` (admin/admin)**
-- Prometheus: `http://localhost:9090`
-- Grafana: `http://localhost:3000`
-
-## ClickHouse: применение DDL и загрузка сэмпла
-
-- DDL/пайплайн описаны в `plans/clickhouse_ddl.md`.
-- Для быстрой загрузки “первых N строк” используйте команды из раздела “Практические заметки для демо”.
-
-## Конвенции по изменениям
-
-- Держать изменения минимальными и по теме задания (инфра, схема, ingest, витрины).
-- Не коммитить секреты. Если требуется пароль/ключи — использовать `.env` и примеры `.env.example`.
-- Оформлять коммиты по правилам из [COMMIT_RULES.md](./docs/COMMIT_RULES.md).
-- README/планы обновлять вместе с изменениями инфраструктуры/DDL.
-- Для спорных или меняющихся API (особенно Airflow/operators/providers) проверять актуальную документацию через `context7` и фиксировать решение в коде/документации.
-- **Комментарии в коде — на русском языке**:
-  - SQL: заголовочный блок с описанием файла, комментарии к каждому логическому блоку
-  - Bash: шапка с назначением/запуском/требованиями, секции разделены `# -----`
-  - См. существующие файлы как пример (`sql/ddl/ods/20_ods.sql`, `sql/dds/30_ods_to_dds.sql`, `scripts/run_batch.sh`)
-
-## Airflow DAGs
-
-### `ddl_init` — Инициализация схемы
-- Запуск: ручной (Trigger DAG)
-- Параметры: `verify_only` (bool, default false)
-- Описание: Создаёт БД и таблицы в ClickHouse от 00_databases до 40_dm
-
-### `kafka_load` — Загрузка в Kafka
-- Запуск: ручный (Trigger DAG with config)
-- Параметры:
-  - `limit` (int, default 0) — количество строк (0 = все)
-  - `reset_topics` (bool, default true) — пересоздать топики
-- Примеры запуска:
-  ```json
-  // Полная загрузка (по умолчанию)
-  {}
-  // Ограниченная загрузка — 100 строк
-  {"limit": 100}
-  ```
-
-### `etl_pipeline` — ETL процесс
-- Запуск: ручной (Trigger DAG with config)
-- Параметры:
-  - `full_refresh` (bool, default true) — очистить DDS перед загрузкой
-- Зависимость: требует наличия данных в STG (от `kafka_load` или `make data`)
-
-## Быстрые проверки
-
-- Kafka ingest: наличие данных в `stg.*` и типизированных строк в `ods.*`.
-- Мониторинг: доступность `/metrics` у ClickHouse и скрейп в Prometheus.
-- **Airflow: `http://localhost:8080` должен показывать UI и DAG `ddl_init`, `kafka_load` и `etl_pipeline`.**
-- BI: витрина `dm.v_events_enriched` должна отвечать за разумное время при фильтре по дате.
-
-## Сценарий работы с Airflow (фаза 2)
-
-```bash
-# 1. Запуск инфраструктуры
-make up
-
-# 2. Инициализация схемы (один раз)
-# Airflow UI → DAGs → ddl_init → Trigger DAG
-
-# 3. Загрузка данных через Airflow (вместо make data)
-# Airflow UI → DAGs → kafka_load → Trigger DAG with config
-# Параметры по умолчанию: limit=0 (полная загрузка), reset_topics=true
-
-# 4. Запуск ETL
-# Airflow UI → DAGs → etl_pipeline → Trigger DAG with config
-# {"full_refresh": true}
-
-# 5. Проверка результатов
-docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM ods.browser_event"
-docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM dds.event"
-docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT * FROM dm.dq_summary"
-```
-
-## Связанная документация
-
-- [README.md](./README.md) — пользовательская документация (быстрый старт, архитектура)
-- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — подробное описание слоёв и технических решений
-- [data/DE-task.md](./data/DE-task.md) — исходное задание
-- [COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов
-
-## Примечания по текущему состоянию (если что-то “не встаёт”)
-
-Репозиторий развивается итеративно; если `docker compose` не стартует из‑за отсутствующих путей/сетей/сервисов, правьте аккуратно и фиксируйте это в `docker-compose.yml` и/или `configs/`.
+- Новые документы создавать в `docs/` (или в профильных подпапках), не в корне репозитория.
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
new file mode 100644
index 0000000..18ea9ea
--- /dev/null
+++ b/docs/OPERATIONS.md
@@ -0,0 +1,94 @@
+# Operations Runbook
+
+Операционный runbook для локального запуска и проверки пайплайна.
+
+## Локальный запуск
+
+Базовые команды:
+
+- `make up` (или `docker compose up -d`)
+- `make ddl` (применяет SQL из `sql/ddl/00_databases.sql` и `sql/ddl/*/*.sql` в ClickHouse)
+- `make data` (пересоздаёт топики и заливает небольшой срез данных в Kafka; полный режим — `FULL=1 make data`)
+- `make transform` (запускает batch-процесс ODS -> DDS -> DM)
+- `docker compose ps`
+- `docker compose logs -f --tail=200 <service>`
+- `docker compose down` (сохраняет named volumes, включая `clickhouse-data`)
+- `docker compose down -v` (удаляет named volumes, использовать осознанно)
+
+## Порты
+
+Порты задаются в `docker-compose.yml`:
+
+- ClickHouse native: `localhost:8002`
+- ClickHouse HTTP: `localhost:9123`
+- Kafka: `localhost:9092`
+- Kafka UI: `http://localhost:8082`
+- Airflow: `http://localhost:8080` (`admin/admin`)
+- Prometheus: `http://localhost:9090`
+- Grafana: `http://localhost:3000`
+
+## Airflow DAGs
+
+### `ddl_init`
+
+- Запуск: ручной (`Trigger DAG`)
+- Параметр: `verify_only` (`bool`, default `false`)
+- Назначение: создаёт БД и таблицы в ClickHouse от `00_databases` до `40_dm`
+
+### `kafka_load`
+
+- Запуск: ручной (`Trigger DAG with config`)
+- Параметры:
+  - `limit` (`int`, default `0`) — количество строк (`0` = все)
+  - `reset_topics` (`bool`, default `true`) — пересоздать топики
+- Примеры:
+
+```json
+{}
+```
+
+```json
+{"limit": 100}
+```
+
+### `etl_pipeline`
+
+- Запуск: ручной (`Trigger DAG with config`)
+- Параметр: `full_refresh` (`bool`, default `true`) — очистить DDS перед загрузкой
+- Зависимость: требует наличия данных в STG (от `kafka_load` или `make data`)
+
+## Рекомендуемый сценарий (фаза 2)
+
+```bash
+# 1. Запуск инфраструктуры
+make up
+
+# 2. Инициализация схемы (один раз)
+# Airflow UI -> DAGs -> ddl_init -> Trigger DAG
+
+# 3. Загрузка данных через Airflow
+# Airflow UI -> DAGs -> kafka_load -> Trigger DAG with config
+# Параметры по умолчанию: limit=0, reset_topics=true
+
+# 4. Запуск ETL
+# Airflow UI -> DAGs -> etl_pipeline -> Trigger DAG with config
+# {"full_refresh": true}
+
+# 5. Проверка результатов
+docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM ods.browser_event"
+docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT count() FROM dds.event"
+docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 --query "SELECT * FROM dm.dq_summary"
+```
+
+## Быстрые проверки
+
+- Kafka ingest: наличие данных в `stg.*` и типизированных строк в `ods.*`.
+- Мониторинг: доступность `/metrics` у ClickHouse и скрейп в Prometheus.
+- Airflow UI: `http://localhost:8080` показывает DAG `ddl_init`, `kafka_load`, `etl_pipeline`.
+- BI: витрина `dm.v_events_enriched` отвечает за разумное время при фильтре по дате.
+
+## Troubleshooting
+
+- `etl_pipeline` падает с ошибкой схемы: сначала запустить `ddl_init`.
+- После `docker compose down -v` нужно повторно прогнать: `ddl_init` -> `kafka_load` -> `etl_pipeline`.
+- Для демо по умолчанию использовать малый срез данных; полный прогон делать осознанно.
diff --git a/docs/REPO_MAP.md b/docs/REPO_MAP.md
new file mode 100644
index 0000000..2a4869b
--- /dev/null
+++ b/docs/REPO_MAP.md
@@ -0,0 +1,48 @@
+# Repo Map
+
+Карта ключевых артефактов репозитория.
+
+## Исполняемые файлы
+
+### Airflow
+
+- `airflow/dags/ddl_init_dag.py` — инициализация схемы ClickHouse
+- `airflow/dags/kafka_load_dag.py` — загрузка в Kafka из JSONL
+- `airflow/dags/etl_pipeline_dag.py` — ETL процесс STG -> ODS -> DDS -> DM
+- `airflow/dags/utils/kafka_helpers.py` — helper-функции для Kafka
+- `airflow/requirements.txt` — зависимости Airflow/ClickHouse plugin
+
+### SQL
+
+- `sql/ddl/00_databases.sql` — создание БД `stg`/`ods`/`dds`/`dm`
+- `sql/ddl/stg/10_stg.sql` — STG (Kafka Engine + MV)
+- `sql/ddl/ods/20_ods.sql` — ODS (типизация + MV для ошибок)
+- `sql/ddl/dds/30_dds.sql` — DDS (таблицы для batch-загрузки)
+- `sql/ddl/dm/40_dm.sql` — DM (витрины VIEW)
+- `sql/dds/30_ods_to_dds.sql` — ODS -> DDS (argMax + JOIN)
+- `sql/dm/40_dds_to_dm.sql` — обновление `dq_summary`
+
+### Скрипты
+
+- `scripts/apply_clickhouse_ddl.sh` — применение DDL
+- `scripts/load_kafka_data.sh` — загрузка в Kafka
+- `scripts/run_batch.sh` — batch-процесс
+
+## Данные и конфиги
+
+- `data/*.jsonl` — исходные данные (могут быть грязными)
+- `configs/` — конфиги ClickHouse, Prometheus, Grafana
+
+## Документация
+
+- `README.md` — быстрый старт и обзор проекта
+- `docs/ARCHITECTURE.md` — техническая архитектура
+- `docs/OPERATIONS.md` — запуск, проверки, troubleshooting
+- `docs/DE-task.md` — исходное задание
+- `docs/COMMIT_RULES.md` — правила коммитов
+
+## Legacy-планы
+
+- `plans/clickhouse_ddl.md` — исходный план (inline DDL)
+- `plans/runbook.md` — ранний runbook
+- `plans/kafka_ingest_plan.md` — ранний план Kafka ingest