docs(repo): переработаны агентские инструкции и карта репозитория

- Зачем:
  - нужно отделить стабильные правила для агента от изменчивой структуры курса и стенда.
- Что:
  - сокращен и переписан AGENTS.md под текущую модель репозитория как курса вокруг Lakehouse-стенда.
  - добавлен docs/maintainer_guide.md с картой репозитория, источниками истины и правилами синхронизации документации.
- Проверка:
  - сверены AGENTS.md и docs/maintainer_guide.md с README.md, START_HERE.md, docs/course_prd.md и docs/course_program.md.

AGENTS.md

@@ -1,57 +1,59 @@
 # Repository Guidelines
 
-This repository contains a small teaching Lakehouse stack (Spark + Trino + Iceberg + MinIO) intended for demos and mentoring.
+Этот репозиторий теперь представляет собой не только локальный Lakehouse-стенд, но и каркас учебного курса `Lakehouse без магии`.
 
-## Project Structure & Module Organization
+В `AGENTS.md` держим только стабильные правила для автоматизированных правок. Изменчивый контекст проекта, карта репозитория и правила синхронизации вынесены в [docs/maintainer_guide.md](docs/maintainer_guide.md).
 
-- `docker-compose.yml`: orchestrates Spark, Trino, MinIO, PostgreSQL, and Jupyter.
-- `spark/`: Spark image (`Dockerfile`) and `spark-defaults.conf`.
-- `jupyter/`: Jupyter image (`Dockerfile`) based on the Spark image.
-- `trino/`: catalog config, e.g. `trino/catalog/lakehouse.properties`.
-- `src/`: PySpark and SQL examples split by engine (`src/spark/...`, `src/trino/...`).
-- `notebooks/`: demo notebooks (mounted into Jupyter at `/opt/work`).
-- `plans/`: internal living docs for implementation plans.
+## Канонические документы
 
-Keep new examples in `src/` or `notebooks/`, and avoid mixing configuration and code.
+- `README.md` — верхнеуровневое описание стенда, архитектуры и сервисов.
+- `START_HERE.md` — первый маршрут для студента до запуска ноутбуков.
+- `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope.
+- `docs/course_program.md` — модульная структура курса и состав учебных материалов.
+- `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений.
+- `plans/` — внутренние living docs; не источник истины для студентского маршрута.
+- `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса.
 
-## Build, Test, and Development Commands
+## Структура репозитория
 
-Run from the repo root:
+- `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` — исполняемый стенд.
+- `notebooks/`, `src/` — учебные материалы и вспомогательные примеры.
+- `docs/`, `START_HERE.md`, `README.md` — входная и методическая документация.
+- `plans/` — внутреннее планирование.
 
-- `docker compose build`: build custom Spark and Jupyter images.
-- `docker compose up -d`: start the full stack in the background.
-- `docker compose ps`: check container status.
-- `docker compose down -v`: stop the stack and remove volumes (for a clean slate).
+Новые учебные примеры держи в `src/` или `notebooks/`, а конфигурацию стенда не смешивай с учебным контентом.
 
-Use `docker compose logs -f <service>` when debugging (`spark-master`, `trino`, `minio`, etc.).
+## Правила изменений
 
-## Coding Style & Naming Conventions
+- Сначала меняй канонический документ для соответствующего слоя, потом синхронизируй связанные ссылки и упоминания.
+- Если меняются сервисы, порты, имена контейнеров, образы или команды запуска, обновляй как минимум `README.md`, `START_HERE.md` и затронутые примеры.
+- Если меняются scope курса, learning outcomes или модульная структура, обновляй `docs/course_prd.md` и `docs/course_program.md`, а не только `plans/`.
+- Поддерживай согласованный маршрут `README -> START_HERE -> docs/course_program.md -> notebooks/src`.
+- Не дублируй крупные фрагменты между документами, если можно сослаться на канонический файл.
+- Legacy-материалы явно помечай как архивные и не возвращай их в основной маршрут без явного запроса.
 
-- Python: PEP 8, 4-space indentation, snake_case for functions, lower_snake_case for files (e.g. `spark_join_demo.py`).
-- SQL: uppercase keywords, `schema.table` naming, short English identifiers; comments may be in Russian.
-- Compose/Docker: service names kebab-case (`spark-master`), env vars UPPER_SNAKE_CASE.
-- Prefer small, focused examples; reuse helpers from `src/` in notebooks where possible.
+## Стиль и содержание
 
-## Testing Guidelines
+- Сохраняй русский язык в student-facing документации, если задача не про перевод.
+- Предпочитай небольшие, сфокусированные примеры и не усложняй стенд без явного запроса.
+- Держи ноутбуки понятными для самостоятельного прохождения; переиспользуемую логику выноси в `src/`.
+- Не добавляй обязательные шаги со скачиванием данных прямо из ноутбуков, если это можно оформить через onboarding-документацию.
 
-There is no formal automated test suite yet. Validate changes by:
+## Проверка изменений
 
-- building and starting the stack, then
-- running `src/spark/cluster_smoke.py` or the SQL in `src/spark/iceberg_demo.sql`,
-- opening `notebooks/01_environment_and_smoke_test.ipynb` in Jupyter and checking it runs end-to-end.
+- Для изменений только в документации проверь согласованность ссылок, терминов и маршрута прохождения.
+- Для изменений стенда сначала используй лёгкую валидацию вроде `docker compose config`.
+- Если меняется поведение стенда или учебных примеров, по возможности проверь сценарии из `src/spark/cluster_smoke.py`, `src/spark/iceberg_smoke.py`, `src/trino/iceberg_smoke.sql` или `notebooks/01_environment_and_smoke_test.ipynb`.
+- Если полная проверка не выполнялась, укажи это явно.
 
-If you add tests, prefer `pytest` under `tests/` and mark slow, integration-heavy tests clearly.
+## Commit & PR Notes
 
-## Commit & Pull Request Guidelines
-
-- Commits: short, descriptive subject in Russian or English, present tense (e.g. `Спарк запускается, создаётся тестовая таблица`, `Add Iceberg join demo`).
-- Keep changes small and focused; update `README.md` when behavior, ports, or images change.
-- PRs should describe the problem, the solution, and any impact on local setup; include screenshots (Trino UI, MinIO, Jupyter) when UI changes are relevant.
+- Коммиты: короткий subject в настоящем времени, на русском или английском.
+- Изменения поведения, портов, маршрута входа или состава материалов обычно требуют обновления документации рядом с кодом.
+- Избегай больших рефакторингов структуры без явного запроса пользователя.
 
 ## Agent-Specific Instructions
 
-When editing as an automated agent:
-
-- Respect this file and avoid large refactors without an explicit request.
-- Preserve Russian user-facing text unless the change is explicitly about translation.
-- Prefer minimal changes that keep the demo simple and robust for newcomers.
+- Уважай существующие изменения пользователя и не откатывай их без запроса.
+- Предпочитай минимальные изменения, которые делают курс проще и устойчивее для новичка.
+- Если непонятно, какой маршрут сейчас актуален, доверяй `START_HERE.md` и `docs/course_program.md`, а не старым HOWTO или планам.

docs/maintainer_guide.md

@@ -0,0 +1,108 @@
+# Карта репозитория и источники истины
+
+Этот документ нужен, чтобы не раздувать `AGENTS.md` и не дублировать изменчивый контекст проекта в нескольких местах.
+
+## Что это за репозиторий сейчас
+
+Репозиторий состоит из двух тесно связанных слоёв:
+
+1. Локальный Lakehouse-стенд на `Spark + Trino + Iceberg + MinIO + PostgreSQL`.
+2. Учебный курс `Lakehouse без магии`, который использует этот стенд как практическую среду.
+
+Из-за этого изменения часто затрагивают не только конфиги и контейнеры, но и маршрут студента по документации и ноутбукам.
+
+## Основные зоны репозитория
+
+| Зона | Где лежит | Назначение |
+| --- | --- | --- |
+| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` | Топология сервисов, образы, конфиги, порты |
+| Onboarding | `README.md`, `START_HERE.md` | Вход в стенд и первый пользовательский маршрут |
+| Course definition | `docs/course_prd.md`, `docs/course_program.md` | Границы курса, learning outcomes, структура модулей |
+| Practice materials | `notebooks/`, `src/` | Практика студента, smoke-скрипты, демонстрации, helper-логика |
+| Internal planning | `plans/` | Внутренние living docs по разработке материалов |
+| Archive | `docs/archive/` | Исторические материалы, не входящие в актуальный маршрут |
+
+## Источники истины
+
+| Файл или каталог | За что отвечает | Что не стоит туда складывать |
+| --- | --- | --- |
+| `docker-compose.yml` | Реальный состав сервисов, контейнеров, сетей, портов и зависимостей | Учебные пояснения, которые не нужны для запуска |
+| `spark/`, `trino/`, `jupyter/` | Конкретные runtime-конфиги и образы | Описание программы курса |
+| `README.md` | Верхнеуровневое объяснение архитектуры стенда и состава репозитория | Пошаговый student onboarding во всех деталях |
+| `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей |
+| `docs/course_prd.md` | Product scope, аудитория, learning outcomes, dataset strategy, out of scope | Технические мелочи запуска контейнеров |
+| `docs/course_program.md` | Модульная структура курса, состав материалов, checkpoints | Подробные docker-команды и legacy-лабы |
+| `notebooks/` | Каноническая практическая часть курса | Длинные инфраструктурные HOWTO |
+| `src/` | Smoke-скрипты, SQL-демо и переиспользуемая helper-логика | Случайные одноразовые заметки и черновики |
+| `plans/` | Внутренний статус работ, живые планы, декомпозиция задач | Источник истины для student-facing маршрута |
+| `docs/archive/` | Справочный legacy-контент | Актуальные инструкции без явной пометки `legacy` |
+
+## Порядок приоритетов, если документы расходятся
+
+- Для реального поведения стенда: `docker-compose.yml` и runtime-конфиги важнее `README.md`.
+- Для первого student onboarding: `START_HERE.md` важнее старых HOWTO и внутренних планов.
+- Для scope курса: `docs/course_prd.md` важнее `plans/`.
+- Для структуры модулей и состава практик: `docs/course_program.md` важнее случайных упоминаний в README или archive-документах.
+
+Если после изменения документы начинают спорить друг с другом, исправляй не только тот файл, который менял, но и ближайший канонический слой.
+
+## Что обновлять при разных типах изменений
+
+### Если меняется стенд
+
+Примеры: новые сервисы, другие порты, переименование контейнеров, изменения образов, новые обязательные env vars.
+
+Минимум проверь и при необходимости обнови:
+
+- `docker-compose.yml`;
+- `README.md`;
+- `START_HERE.md`;
+- затронутые команды в `src/`, ноутбуках и планах.
+
+### Если меняется маршрут студента
+
+Примеры: новый первый ноутбук, другой onboarding-flow, перенос шагов из README в отдельный документ.
+
+Минимум проверь и при необходимости обнови:
+
+- `START_HERE.md`;
+- `docs/course_program.md`;
+- соответствующие `notebooks/`;
+- `README.md`, если меняется верхнеуровневый вход в репозиторий.
+
+### Если меняется scope курса
+
+Примеры: новый обязательный модуль, изменение learning outcomes, перенос темы в backlog, смена основного датасета.
+
+Минимум проверь и при необходимости обнови:
+
+- `docs/course_prd.md`;
+- `docs/course_program.md`;
+- релевантные `plans/`;
+- student-facing материалы, если scope уже отражён в них явно.
+
+### Если добавляется новый учебный материал
+
+Примеры: новый ноутбук, новый smoke-скрипт, новый SQL demo.
+
+Обычно нужно:
+
+- положить практику в `notebooks/` или `src/`;
+- отразить её в `docs/course_program.md`, если материал входит в основной трек;
+- при необходимости обновить `START_HERE.md`, если это новая точка входа;
+- не раздувать `README.md` подробностями модуля, если это уже описано в программе курса.
+
+## Что не стоит держать в AGENTS.md
+
+- Полную программу курса по модулям.
+- Подробные таблицы портов и runtime-параметров.
+- Длинные HOWTO и лабораторные сценарии.
+- Исторические объяснения того, как стенд выглядел раньше.
+
+`AGENTS.md` должен оставаться коротким набором правил. Всё, что часто меняется вместе с курсом и стендом, лучше хранить в обычной документации.
+
+## Работа с legacy-материалами
+
+- `docs/archive/` хранит полезный контекст, но не определяет текущий маршрут курса.
+- Если старый материал нужен как reference, оставляй его в archive и явно помечай, почему он не канонический.
+- Если legacy-документ снова становится частью основного курса, переноси его обратно в актуальную структуру, а не оставляй полуживой копией.