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.

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-документ снова становится частью основного курса, переноси его обратно в актуальную структуру, а не оставляй полуживой копией.