docs(course): добавлены glossary, mentor notes, шпаргалка и переписан README

- Зачем:
  - закрыты 3 вспомогательных артефакта из course_program.md §3.3: glossary, cheat sheet, mentor notes.
  - README переписан с фокусом на ценность для студента.
- Что:
  - создан docs/glossary.md (16 терминов, сгруппированных по темам с параллелями к DWH).
  - создан docs/mentor_notes.md (тайминг, типичные вопросы, checkpoint-ы, формат «менти работает сам»).
  - добавлена секция «Краткая шпаргалка» в docs/stack_reference.md (S3-пути, таблицы, SQL-команды, маунты).
  - README.md переписан: лид с навыками, убрано дублирование со stack_reference.
  - обновлены перекрёстные ссылки в AGENTS.md, course_program.md, maintainer_guide.md.
- Проверка:
  - все ссылки между документами валидны (glossary.md, mentor_notes.md существуют).
  - термины glossary и команды шпаргалки верифицированы по содержимому ноутбуков.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

AGENTS.md

@@ -11,6 +11,8 @@
 - `docs/stack_reference.md` — технический reference по сервисам, портам, доступу и smoke-тестам.
 - `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope.
 - `docs/course_program.md` — модульная структура курса и состав учебных материалов.
+- `docs/glossary.md` — справочник терминов курса.
+- `docs/mentor_notes.md` — заметки для ведения курса с ментором (опционально).
 - `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений.
 - `plans/` — внутренние living docs; не источник истины для студентского маршрута.
 - `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса.

README.md

@@ -1,16 +1,23 @@
-# Lakehouse без магии: локальный стенд и учебные материалы
+# Lakehouse без магии
 
-Этот репозиторий объединяет:
+Практический курс, после которого ты будешь уверенно работать с Lakehouse-стеком: поднимать стенд, строить пайплайн `raw -> bronze -> silver`, читать одну таблицу из двух движков и не бояться изменений в данных.
 
-- локальный Lakehouse-стенд на `Spark + Trino + Iceberg + MinIO + PostgreSQL`;
-- учебный курс `Lakehouse без магии`, который использует этот стенд как практическую среду;
-- стартовые ноутбуки и demo-скрипты для первых экспериментов.
+## Что ты получишь
 
-Репозиторий рассчитан не на «универсальную платформу для всего», а на понятную локальную песочницу, где можно руками пройти путь от запуска стенда до чтения одной и той же Iceberg-таблицы из `Spark` и `Trino`.
+После прохождения 8 модулей ты умеешь:
 
-## Архитектура
+1. **Поднимать и диагностировать** локальный Lakehouse-стенд — не по инструкции, а с пониманием, что и зачем работает.
+2. **Объяснять архитектуру** `storage + catalog + compute` — и видеть, как знакомые концепции из PostgreSQL/Greenplum ложатся на новый стек.
+3. **Строить пайплайн** `raw -> bronze -> silver` на реальном датасете NYC Taxi — с проверками качества и воспроизводимостью.
+4. **Работать с двумя движками** — записывать данные через Spark, читать через Trino, и понимать, почему это работает без копирования.
+5. **Безопасно менять таблицы** — schema evolution, time travel, rollback к предыдущему состоянию вместо паники.
+6. **Обслуживать таблицы** — compaction и expire_snapshots, с пониманием параллелей к VACUUM/REORGANIZE.
 
-Ниже показана упрощённая рабочая схема стенда: пользователь входит через `JupyterLab` и `Trino UI / CLI`, а `Spark` и `Trino` независимо работают поверх общего `storage` и общего `catalog`.
+Курс рассчитан на `~12-15 часов` самостоятельной работы. Каждый модуль: объяснение, демонстрация, самостоятельное задание, checkpoint.
+
+## Стек
+
+Всё работает локально в Docker. Никаких облаков, внешних зависимостей и регистраций.
 
 ```mermaid
 graph TB
@@ -41,23 +48,21 @@ graph TB
     T --> M
 ```
 
-Коротко по ролям:
-
-- `MinIO` хранит данные и служебные файлы Iceberg.
-- `PostgreSQL` хранит метаданные JDBC-каталога `lakehouse`.
-- `Spark` и `Trino` работают как два compute-движка поверх одного storage и одного catalog.
-- `JupyterLab` служит основной точкой входа в практическую часть курса.
-- `Trino UI / CLI` даёт отдельную точку входа для ad hoc SQL и проверки таблиц.
+| Компонент | Роль в стенде |
+| --- | --- |
+| `MinIO` | Storage — хранит данные и служебные файлы Iceberg |
+| `PostgreSQL` | Catalog — метаданные JDBC-каталога `lakehouse` |
+| `Spark` | Compute — ETL, запись и чтение Iceberg-таблиц |
+| `Trino` | Compute — ad hoc SQL, чтение тех же таблиц |
+| `JupyterLab` | Точка входа — практические ноутбуки курса |
 
 ## С чего начать
 
-Если ты заходишь в репозиторий впервые, используй такой маршрут:
+1. Открой [START_HERE.md](./START_HERE.md) — запуск стенда, диагностика, первый ноутбук.
+2. Пройди `notebooks/01_environment_and_smoke_test.ipynb`.
+3. Дальше по порядку: [docs/course_program.md](./docs/course_program.md).
 
-1. Открой [START_HERE.md](./START_HERE.md) для первого запуска стенда и базовой диагностики.
-2. После старта стенда выполни `notebooks/01_environment_and_smoke_test.ipynb`.
-3. Для структуры курса смотри [docs/course_program.md](./docs/course_program.md).
-
-Если нужен только краткий запуск, из корня репозитория достаточно:
+Краткий запуск из корня репозитория:
 
 ```bash
 docker compose build
@@ -65,54 +70,25 @@ docker compose up -d
 docker compose ps
 ```
 
-Основные UI после старта:
+После старта:
 
-- Spark Master UI: `http://localhost:8080`
-- Trino UI: `http://localhost:8090`
-- MinIO Console: `http://localhost:9001`
-- JupyterLab: `http://localhost:8888`
-
-Полный onboarding, диагностика и reset-сценарии находятся в `START_HERE.md`.
-
-## Как устроен репозиторий
-
-| Где | Что лежит |
+| UI | Адрес |
 | --- | --- |
-| `docker-compose.yml` | состав сервисов стенда, порты, сети, init-контейнеры |
-| `spark/` | Dockerfile и конфиг Spark для Iceberg + MinIO |
-| `trino/` | каталог `lakehouse` и настройки Trino |
-| `jupyter/` | образ JupyterLab на базе Spark-образа |
-| `notebooks/` | практические ноутбуки курса |
-| `src/` | smoke-скрипты, SQL-демо и helper-логика |
-| `docs/` | PRD, программа курса, reference-документы |
-| `plans/` | внутренние living docs по развитию материалов |
+| JupyterLab | `http://localhost:8888` |
+| Spark Master | `http://localhost:8080` |
+| Trino | `http://localhost:8090` |
+| MinIO Console | `http://localhost:9001` |
 
-## Основные документы для прохождения
+## Документы для прохождения
 
-- [START_HERE.md](./START_HERE.md) — первый маршрут для студента.
+- [START_HERE.md](./START_HERE.md) — первый маршрут: prerequisites, запуск, диагностика.
 - [docs/course_program.md](./docs/course_program.md) — модульная структура и состав учебных материалов.
-- [docs/stack_reference.md](./docs/stack_reference.md) — технический reference по сервисам, портам, конфигам и smoke-тестам.
+- [docs/stack_reference.md](./docs/stack_reference.md) — порты, команды, конфиги, шпаргалка.
+- [docs/glossary.md](./docs/glossary.md) — справочник терминов (storage, catalog, compute, snapshot и др.).
 
-## Что уже можно делать в стенде
+## Менторство
 
-- поднять локальный кластер `Spark` с двумя worker-ами;
-- создать Iceberg-таблицу из `Spark`;
-- прочитать ту же таблицу из `Trino`;
-- пройти базовый smoke test через ноутбук или demo-скрипты;
-- использовать стенд как основу для следующих модулей курса.
-
-## Куда смотреть за техническими деталями
-
-- [docs/stack_reference.md](./docs/stack_reference.md) — сервисы, порты, доступ, reset, smoke tests;
-- [spark/spark-defaults.conf](./spark/spark-defaults.conf) — конфигурация Spark-каталога `lakehouse`;
-- [trino/catalog/lakehouse.properties](./trino/catalog/lakehouse.properties) — конфигурация каталога Trino;
-- [docker-compose.yml](./docker-compose.yml) — фактический состав стенда.
-
-## Автор и менторство
-
-Этот репозиторий и материалы курса можно проходить самостоятельно, но при желании их можно разбирать вместе с автором как с ментором по `Data Engineering`.
-
-Если хочешь глубже пройти темы `Spark`, `Trino`, `Iceberg`, `Lakehouse` и связанные практики по `DE`, напиши: [@dementev_dev](https://t.me/dementev_dev).
+Курс рассчитан на самостоятельное прохождение, но если хочешь разобрать темы глубже с ментором по Data Engineering — напиши: [@dementev_dev](https://t.me/dementev_dev).
 
 ## Лицензия
 

docs/course_program.md

@@ -59,9 +59,9 @@
 
 * вспомогательные скрипты в `src/spark` и `src/trino`;
 * инструкции по загрузке или подготовке учебных датасетов;
-* краткий glossary по терминам `storage`, `catalog`, `compute`, `table format`, `namespace`, `metadata`, `manifest`, `snapshot`, `time travel`, `schema evolution`, `compaction`, `vacuum`;
-* cheat sheet по типовым командам, адресам сервисов, ключевым путям и точкам входа;
-* опционально, отдельные mentor notes для ведения курса с ментором.
+* краткий [glossary](./glossary.md) по терминам `storage`, `catalog`, `compute`, `table format`, `namespace`, `metadata`, `manifest`, `snapshot`, `time travel`, `schema evolution`, `compaction`, `vacuum`;
+* [шпаргалка](./stack_reference.md#краткая-шпаргалка) по типовым командам, адресам сервисов, ключевым путям и точкам входа (секция в `stack_reference.md`);
+* опционально, [заметки для ментора](./mentor_notes.md) для ведения курса с ментором.
 
 ## 4. Трассировка Learning Outcomes на модули
 

docs/glossary.md

@@ -0,0 +1,137 @@
+# Глоссарий курса
+
+Краткий справочник терминов, сгруппированных по темам. Если нужен полный технический reference стенда, используй [stack_reference.md](./stack_reference.md).
+
+## Архитектура Lakehouse
+
+### Storage
+
+Физическое хранилище файлов. Хранит data files, metadata-файлы Iceberg и raw-данные.
+
+**В этом курсе:** MinIO (`s3a://lakehouse/`).
+**Параллель с DWH:** каталог `pg_data` в PostgreSQL, только вынесенный за пределы СУБД.
+**Где в курсе:** Модули 1, 2, 3.
+
+### Catalog
+
+Реестр метаданных таблиц: какие таблицы существуют, где лежат их данные, какова текущая схема. Не хранит сами данные.
+
+**В этом курсе:** PostgreSQL (JDBC catalog `lakehouse`).
+**Параллель с DWH:** системный каталог `pg_catalog` в PostgreSQL.
+**Где в курсе:** Модули 2, 4, 6.
+
+### Compute
+
+Вычислительный движок, который читает метаданные из каталога и данные из хранилища для выполнения запросов. Не владеет ни данными, ни метаданными.
+
+**В этом курсе:** Spark (запись и чтение), Trino (чтение и ad hoc SQL).
+**Параллель с DWH:** процесс СУБД PostgreSQL/Greenplum, но в Lakehouse движков может быть несколько одновременно.
+**Где в курсе:** Модули 1, 2, 6.
+
+### Table format
+
+Спецификация, определяющая, как таблица организована на уровне файлов: какие data files входят в таблицу, где лежат метаданные, как работают snapshot-ы. Это не база данных и не хранилище — это набор правил.
+
+**В этом курсе:** Apache Iceberg.
+**Параллель с DWH:** ближайший аналог — формат хранения таблицы (heap / AppendOnly в Greenplum), но table format в Lakehouse делает больше: он управляет историей, схемой и файлами.
+**Где в курсе:** Модули 2, 4.
+
+### Decoupled compute
+
+Принцип, при котором вычислительные движки не зависят друг от друга и от хранилища. Один движок может писать, другой — читать те же данные без копирования, потому что оба обращаются к общему каталогу и хранилищу.
+
+**В этом курсе:** Spark пишет таблицу, Trino читает ту же таблицу через общий JDBC-каталог.
+**Параллель с DWH:** в классическом DWH вычислитель один, поэтому проблема не возникает.
+**Где в курсе:** Модуль 6.
+
+## Структура Iceberg-таблицы
+
+### Namespace
+
+Логическая группа таблиц внутри каталога. Используется для организации таблиц по слоям или доменам.
+
+**В этом курсе:** `bronze`, `silver`, `default` — namespace-ы внутри каталога `lakehouse`.
+**Параллель с DWH:** `schema` в PostgreSQL.
+**Где в курсе:** Модули 4, 5.
+
+### Metadata
+
+JSON-файлы, описывающие текущее состояние таблицы: схему, свойства, список snapshot-ов. Лежат в каталоге `metadata/` рядом с data files в хранилище.
+
+**В этом курсе:** файлы в `s3a://lakehouse/warehouse/<namespace>/<table>/metadata/`.
+**Параллель с DWH:** системные таблицы `pg_catalog`, но вынесенные в файлы.
+**Где в курсе:** Модули 2, 4.
+
+### Manifest
+
+Avro-файл со списком data files и их статистиками (количество строк, диапазоны значений колонок). Позволяет движку пропускать ненужные файлы при чтении.
+
+**В этом курсе:** видны при осмотре структуры таблицы в MinIO.
+**Где в курсе:** Модуль 4.
+
+### Manifest list
+
+Avro-файл со списком manifest-ов, составляющих один snapshot. Каждый snapshot ссылается на свой manifest list.
+
+**В этом курсе:** видны как часть внутренней структуры Iceberg при исследовании MinIO.
+**Где в курсе:** Модуль 4.
+
+### Snapshot
+
+Неизменяемая версия таблицы, зафиксированная в момент операции с данными (INSERT, overwrite, delete). Каждый snapshot определяет, какие data files составляли таблицу в конкретный момент. Как коммит в git.
+
+**В этом курсе:** `SELECT * FROM table.snapshots` показывает историю snapshot-ов.
+**Параллель с DWH:** бэкап или PITR (Point-In-Time Recovery), но значительно легче: snapshot-ы создаются автоматически и не требуют копирования данных.
+**Где в курсе:** Модули 4, 7, 8.
+
+## Операции
+
+### Time travel
+
+Чтение таблицы в состоянии на момент определённого snapshot-а. Позволяет сравнить текущие данные с предыдущими или восстановить потерянную информацию. В Spark: `VERSION AS OF <snapshot_id>`, в Trino: `FOR VERSION AS OF <snapshot_id>`.
+
+**В этом курсе:** демонстрация на демо-таблице в Модуле 7.
+**Параллель с DWH:** восстановление из бэкапа (pg_dump / PITR), но без остановки сервиса и без восстановления всей базы целиком.
+**Где в курсе:** Модуль 7.
+
+### Schema evolution
+
+Изменение схемы таблицы (добавление, переименование, удаление колонок) без перезаписи data files. Метаданные обновляются, данные остаются на месте.
+
+**В этом курсе:** `ALTER TABLE ADD COLUMNS`, `ALTER TABLE RENAME COLUMN`.
+**Параллель с DWH:** `ALTER TABLE` в PostgreSQL, но в Iceberg старые data files не перезаписываются — новые колонки возвращают NULL для существующих строк.
+**Где в курсе:** Модули 7, 8.
+
+### Compaction (rewrite_data_files)
+
+Объединение множества мелких data files в меньшее количество крупных. Решает проблему деградации чтения после множества мелких INSERT-ов. Данные не меняются, только реорганизуются файлы.
+
+**В этом курсе:** `CALL lakehouse.system.rewrite_data_files(table => '...')`.
+**Параллель с DWH:** `ALTER TABLE ... REORGANIZE` в Greenplum AppendOnly.
+**Где в курсе:** Модуль 8.
+
+### Vacuum (expire_snapshots)
+
+Удаление старых snapshot-ов и связанных с ними data files из хранилища. Освобождает место, но делает невозможным time travel к удалённым snapshot-ам. Необратимая операция.
+
+**В этом курсе:** `CALL lakehouse.system.expire_snapshots(table => '...', retain_last => N)`.
+**Параллель с DWH:** `VACUUM` в PostgreSQL/Greenplum (удаление мёртвых строк).
+**Где в курсе:** Модуль 8.
+
+## Слои данных
+
+### Raw
+
+Неизменяемые исходные файлы, загруженные из внешнего источника. Хранятся в S3 как обычные файлы (Parquet, CSV), а не как Iceberg-таблицы. Точка воспроизводимости: если что-то пошло не так на следующих слоях, всегда можно перестроить пайплайн от raw.
+
+**В этом курсе:** `s3a://lakehouse/raw/nyc_taxi/` — Parquet-файлы NYC Taxi.
+**Параллель с DWH:** staging-зона (stg), внешние таблицы.
+**Где в курсе:** Модуль 3.
+
+### Bronze / Silver
+
+Управляемые Iceberg-таблицы с разным уровнем обработки. Bronze — данные «как есть» из raw, загруженные в Iceberg-таблицу. Silver — очищенные и трансформированные данные, готовые для анализа.
+
+**В этом курсе:** `lakehouse.bronze.nyc_taxi_yellow` (bronze), `lakehouse.silver.nyc_taxi_yellow` (silver).
+**Параллель с DWH:** ODS (bronze) / DDS (silver).
+**Где в курсе:** Модули 4 (bronze), 5 (silver), 8 (финальная практика).

docs/maintainer_guide.md

@@ -21,6 +21,7 @@
 | Onboarding | `README.md`, `START_HERE.md` | Вход в репозиторий и первый пользовательский маршрут |
 | Runtime reference | `docs/stack_reference.md` | Технические детали стенда: порты, доступ, команды, smoke-тесты |
 | Course definition | `docs/course_prd.md`, `docs/course_program.md` | Границы курса, learning outcomes, структура модулей |
+| Reference materials | `docs/glossary.md`, `docs/mentor_notes.md` | Справочник терминов и заметки для ментора |
 | Practice materials | `notebooks/`, `src/` | Практика студента, smoke-скрипты, демонстрации, helper-логика |
 | Internal planning | `plans/` | Внутренние living docs по разработке материалов |
 | Archive | `docs/archive/` | Исторические материалы, не входящие в актуальный маршрут |

docs/mentor_notes.md

@@ -0,0 +1,108 @@
+# Заметки для ментора
+
+Этот документ — для ведения курса с ментором. Студенту он не нужен.
+
+## Формат работы
+
+Менти работает преимущественно самостоятельно. Ноутбуки написаны так, чтобы студент мог пройти демо-часть и самостоятельные задания без посторонней помощи.
+
+Роль ментора:
+- **задать направление** — обозначить, на что обратить внимание в модуле, какие параллели с текущим опытом студента искать;
+- **отвечать на вопросы** — по ходу прохождения или на checkpoint-е;
+- **не вести за руку** — не объяснять материал до того, как студент попробовал сам.
+
+Типичный цикл: ментор даёт задание на модуль → менти проходит самостоятельно → встреча для обсуждения вопросов и checkpoint-а.
+
+## Ориентировочный тайминг
+
+| Модуль | Тема | Самостоятельная работа | Обсуждение с ментором | Комментарий |
+| --- | --- | --- | --- | --- |
+| 1 | Вход в стенд | 30-40 мин | 10-15 мин | Если Docker знаком, идёт быстро |
+| 2 | Ментальная модель | 40-60 мин | 15-20 мин | Ключевой модуль; убедись, что студент заходил в MinIO |
+| 3 | Raw-данные | 40-50 мин | 10 мин | Зависит от скорости загрузки данных |
+| 4 | Bronze + Iceberg | 60-80 мин | 15-20 мин | Первая таблица — много новых концепций |
+| 5 | Silver | 50-70 мин | 15 мин | Трансформации + проверки качества |
+| 6 | Spark + Trino | 40-60 мин | 15 мин | Если DBeaver настроен заранее — быстрее |
+| 7 | Schema evolution, time travel | 60-80 мин | 15-20 мин | Rollback требует внимания |
+| 8 | Обслуживание + финальная | 80-120 мин | 20-30 мин | Финальная практика занимает больше всего |
+
+Общий объём самостоятельной работы: ~12-15 часов. Время с ментором: ~2-2.5 часа суммарно (по 15-20 минут на модуль).
+
+## Типичные вопросы и затруднения
+
+С чем студент, скорее всего, придёт к тебе.
+
+### Модуль 1. Вход в стенд
+
+- **Docker не хватает ресурсов.** Стенд требует ~4-6 ГБ RAM. На машинах с 8 ГБ бывают проблемы. Решение: увеличить лимиты Docker Desktop или закрыть лишние приложения.
+- **Порты заняты.** 8080, 8888, 9000 — популярные порты. `docker compose ps` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`.
+- **Студент не читает `START_HERE.md`.** Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу.
+
+### Модуль 2. Ментальная модель
+
+- **Путаница storage vs catalog.** Студент думает, что MinIO — это база данных. Помогает аналогия: MinIO — это «диск», PostgreSQL — это «оглавление книги», Spark — это «читатель».
+- **«Зачем нужен отдельный каталог?»** Объясни через decoupled compute: два движка могут работать с одними данными, только если есть общий реестр таблиц.
+- **Студент не заходит в MinIO Console.** Без визуального осмотра файлов модель остаётся абстрактной. Попроси студента найти конкретные data files в MinIO.
+
+### Модуль 3. Raw-данные
+
+- **Путь к данным не совпадает.** Студент скачал данные, но положил не в `./data/nyc_taxi/`. Проверь монтирование: файлы должны быть видны внутри контейнера по пути `/opt/data/nyc_taxi/`.
+- **Ошибки чтения Parquet.** Иногда файл скачивается не полностью. Решение: перекачать файл.
+- **Студент хочет «починить» raw-данные.** Объясни принцип неизменяемости raw: чистка — задача следующих слоёв.
+
+### Модуль 4. Bronze + Iceberg
+
+- **Ошибки при CREATE TABLE.** Обычно namespace не создан. Проверь, что `CREATE NAMESPACE lakehouse.bronze` выполнен.
+- **Студент не понимает разницу между Parquet-файлами и Iceberg-таблицей.** Помогает осмотр MinIO: Iceberg-таблица содержит `metadata/` с JSON и Avro-файлами, а не просто набор Parquet.
+- **Самостоятельное задание (taxi_zone_lookup) сложнее, чем кажется.** CSV-файл требует чтения через `spark.read.csv()` с заголовками. Подсказка в ноутбуке есть, но студенты часто пропускают её.
+
+### Модуль 5. Silver
+
+- **Ошибки в трансформациях.** Студент путает порядок операций (фильтрация до/после JOIN). Помоги разобрать логику пошагово.
+- **Не знает PySpark API.** Если студент привык к чистому SQL, покажи эквивалентный SQL через `spark.sql()` — он поддерживается наравне с DataFrame API.
+- **Проверки качества кажутся «лишними».** Объясни, что в production без проверок ошибки обнаруживаются на этапе отчётов, когда уже поздно.
+
+### Модуль 6. Spark + Trino
+
+- **Trino не видит таблицу.** Обычно Trino не успел стартовать или каталог не настроен. Проверь `docker compose logs trino` и убедись, что контейнер `healthy`.
+- **DBeaver не подключается.** Host: `localhost`, Port: `8090`, User: любая строка, Password: пусто. Драйвер Trino встроен в DBeaver.
+- **«Зачем два движка, если Spark всё умеет?»** В production Trino используется для ad hoc запросов аналитиками, которые не работают с Spark. Разделение ролей: Spark — ETL, Trino — BI/analytics.
+
+### Модуль 7. Schema evolution и time travel
+
+- **Студент путает schema evolution и data snapshot.** `ALTER TABLE ADD COLUMNS` не создаёт новый data snapshot — это metadata-only операция. Snapshot создаётся только при изменении данных (INSERT, DELETE и т.д.).
+- **Time travel: забывает сохранить snapshot_id.** Без сохранённого ID в переменную приходится заново запрашивать `table.snapshots`. Привычка: перед экспериментом запиши ID текущего состояния.
+- **`rollback_to_snapshot` vs `CREATE OR REPLACE`.** Ключевое отличие: rollback сохраняет историю, `CREATE OR REPLACE` уничтожает её. Это описано в Секции 10 ноутбука.
+
+### Модуль 8. Обслуживание и финальная практика
+
+- **8 INSERT-ов в демо-таблице идут медленно.** Каждый INSERT запускает отдельный Spark job. На слабых машинах может занять 2-3 минуты. Это нормально.
+- **Студент запускает expire перед compaction.** Порядок важен: сначала compaction, потом expire. Иначе старые мелкие файлы становятся «сиротами».
+- **Финальная практика: ошибка несовпадения колонок при INSERT.** После `ADD COLUMNS (processed_at)` INSERT требует указания всех колонок, включая `processed_at`. Подсказка есть в описании шага 6.
+
+## Checkpoint-ы: как использовать
+
+Checkpoint — не тест. Это повод для короткого разговора. Студент уже ответил на вопросы сам (они есть в ноутбуке), задача ментора — проверить понимание и дополнить, если нужно.
+
+Что работает:
+- **Попросить объяснить своими словами**, а не зачитать ответ. «Расскажи, как ты понимаешь, что такое snapshot» лучше, чем «что такое snapshot?».
+- **Связать с опытом студента.** Параллели с PostgreSQL/Greenplum есть в каждом модуле — используй их.
+- **3-4 вопросов достаточно.** Если студент уверенно отвечает на первые, не нужно проходить весь список.
+- **Финальный checkpoint (Модуль 8) — самый важный.** Часть B покрывает весь курс. Хороший признак: студент объясняет, почему Spark и Trino видят одну таблицу, без подсказок.
+
+## Если студент опытный
+
+Некоторые модули можно ускорить для студентов с опытом в DE/DWH:
+
+| Модуль | Можно ускорить? | Что пропустить | Что нельзя пропускать |
+| --- | --- | --- | --- |
+| 1 | Да | Детальную диагностику Docker | Проверку, что все UI доступны |
+| 2 | Частично | Базовые пояснения про storage/catalog | Практический осмотр MinIO и PostgreSQL |
+| 3 | Да | Пояснения про raw-зону | Загрузку данных (без неё не работают Модули 4-8) |
+| 4 | Нет | — | Создание таблицы и осмотр структуры Iceberg |
+| 5 | Частично | Базовые трансформации | Проверки качества и принцип воспроизводимости |
+| 6 | Нет | — | Практику с Trino (даже если студент знает Trino) |
+| 7 | Нет | — | Time travel и rollback — ядро безопасной работы |
+| 8 | Нет | — | Финальная практика — итоговая проверка всех навыков |
+
+**Модули 4, 6, 7, 8 нельзя пропускать** даже для опытных студентов. Они содержат ключевые практики, которые отличают «знаю теорию» от «умею делать руками».

docs/stack_reference.md

@@ -172,9 +172,69 @@ docker compose exec spark-master \
   /opt/spark/bin/spark-sql -e "DROP TABLE IF EXISTS lakehouse.default.spark_trino_smoke"
 ```
 
+## Краткая шпаргалка
+
+### Ключевые S3-пути курса
+
+| Путь | Назначение |
+| --- | --- |
+| `s3a://lakehouse/raw/nyc_taxi/` | raw-зона: исходные Parquet и CSV |
+| `s3a://lakehouse/warehouse/bronze/` | bronze-таблицы Iceberg |
+| `s3a://lakehouse/warehouse/silver/` | silver-таблицы Iceberg |
+
+### Основные таблицы курса
+
+| Таблица | Создаётся в |
+| --- | --- |
+| `lakehouse.bronze.nyc_taxi_yellow` | Модуль 4 |
+| `lakehouse.bronze.taxi_zone_lookup` | Модуль 4 (самостоятельное задание) |
+| `lakehouse.silver.nyc_taxi_yellow` | Модуль 5 |
+
+### Часто используемые Spark SQL
+
+```sql
+-- Просмотр структуры каталога
+SHOW TABLES IN lakehouse.bronze;
+
+-- Метаданные Iceberg
+SELECT * FROM <table>.snapshots;
+SELECT * FROM <table>.files;
+
+-- Обслуживание (Модуль 8)
+CALL lakehouse.system.rewrite_data_files(table => '<namespace>.<table>');
+CALL lakehouse.system.expire_snapshots(table => '<namespace>.<table>', retain_last => N);
+
+-- Rollback (Модуль 7)
+CALL lakehouse.system.rollback_to_snapshot(table => '<namespace>.<table>', snapshot_id => <id>);
+
+-- Time travel (Модуль 7)
+SELECT * FROM <table> VERSION AS OF <snapshot_id>;
+```
+
+### Часто используемые Trino SQL
+
+```sql
+SHOW SCHEMAS FROM lakehouse;
+SHOW TABLES FROM lakehouse.silver;
+DESCRIBE lakehouse.silver.nyc_taxi_yellow;
+
+-- Time travel (синтаксис Trino)
+SELECT * FROM <table> FOR VERSION AS OF <snapshot_id>;
+```
+
+### Монтирование (хост → контейнер)
+
+| Хост | Контейнер | Режим |
+| --- | --- | --- |
+| `./notebooks` | `/opt/work` | read-write |
+| `./src` | `/opt/src` | read-only |
+| `./data` | `/opt/data` | read-only |
+
 ## Когда какой документ использовать
 
 - `README.md` — чтобы понять, что это за репозиторий и куда идти дальше.
 - `START_HERE.md` — чтобы впервые поднять стенд и пройти Модуль 1.
-- `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа и smoke-тесты.
+- `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа, шпаргалку и smoke-тесты.
 - `course_program.md` — чтобы понять учебную траекторию дальше первого модуля.
+- `glossary.md` — чтобы вернуться к определению термина (storage, catalog, compute, snapshot и др.).
+- `mentor_notes.md` — заметки для ведения курса с ментором (опционально).