docs: clarify learner workflow and resource requirements

docs/course_program.md

@@ -1,6 +1,29 @@
 # Программа учебного курса: Lakehouse без магии
 
-Этот документ заменяет предыдущий черновой план и выравнивает программу с PRD из [course_prd.md](./course_prd.md).
+Здесь собраны порядок модулей, ссылки на ноутбуки и результаты, по которым можно
+проверить свою работу. Рамки курса и learning outcomes описаны в [course_prd.md](./course_prd.md).
+
+## Маршрут по модулям
+
+Перед первым уроком подготовь стенд по [START_HERE](../START_HERE.md).
+Дальше проходи ноутбуки по порядку: файлы и таблицы из ранних модулей нужны в
+следующих. Пауза между занятиями описана в [памятке учащегося](./study_workflow.md).
+
+| Модуль и ноутбук | Что понадобится | Результат перед переходом дальше |
+| --- | --- | --- |
+| [1. Вход в стенд](../notebooks/01_environment_and_smoke_test.ipynb) | Работающий стенд | Smoke test вернул `499999500000`; ты можешь показать два worker-а и объяснить роли сервисов |
+| [2. Модель Lakehouse](../notebooks/02_lakehouse_mental_model.ipynb) | Модуль 1 | Ты нашел файлы демо-таблицы в MinIO и запись каталога в PostgreSQL; выполнил очистку демо по ноутбуку |
+| [3. Исходные данные](../notebooks/03_raw_ingest_and_first_read.ipynb) | [Четыре файла Taxi](../START_HERE.md#подготовка-учебного-датасета-перед-модулем-3) на хосте | Файлы загружены в raw-зону MinIO, Spark читает их; проверены схема и основные метрики |
+| [4. Bronze и Iceberg](../notebooks/04_bronze_with_iceberg.ipynb) | Raw-файлы из Модуля 3 | Созданы bronze-таблица поездок и таблица зон из самостоятельного задания; видны их данные и metadata-файлы |
+| [5. Silver](../notebooks/05_silver_layer.ipynb) | Обе bronze-таблицы | Создана silver-таблица, проверены правила очистки и качество результата |
+| [6. Spark и Trino](../notebooks/06_spark_and_trino_on_same_table.ipynb) | Silver из Модуля 5; DBeaver по желанию | Одна таблица читается обоими движками; ты можешь объяснить, какие компоненты у них общие |
+| [7. Изменения таблиц](../notebooks/07_safe_table_changes.ipynb) | Результаты предыдущих модулей | На демо-таблице проверены изменение схемы, чтение прошлого состояния и rollback; silver сохранена |
+| [8. Обслуживание и финальная практика](../notebooks/08_maintenance_and_final_lab.ipynb) | Raw, bronze и silver | Проверено обслуживание таблиц; самостоятельно пройден поток от исходных файлов до чтения и проверок результата |
+
+В каждом ноутбуке сначала прочитай объяснение, затем выполни демонстрацию и
+самостоятельное задание. Checkpoint в конце урока — вопросы и проверки для
+самопроверки. Сохраненный вывод помогает вернуться к результату, но не заменяет
+собственный запуск и объяснение.
 
 ## 1. Рамка курса
 
@@ -40,7 +63,9 @@
 * пошаговый гайд по запуску стенда: `build`, `up`, проверка сервисов, открытие UI;
 * краткое объяснение, как запускать Jupyter-ноутбуки в браузерном VS Code, где лежат ноутбуки и как читать структуру урока;
 * troubleshooting по типовым проблемам старта;
-* инструкция по reset/restart стенда для повторного прохождения практик.
+* [памятка учащегося](./study_workflow.md): продолжение занятия, сохранение данных,
+  перезапуск ядра и диагностика;
+* отдельная инструкция по сбросу учебных данных для повторного прохождения практик.
 
 **Что должен закрывать этот слой:**
 
@@ -85,7 +110,7 @@
 
 **Содержание:**
 
-* запуск `docker compose build` и `docker compose up -d`;
+* скачивание готовых образов, сборка окружения и запуск по `START_HERE.md`;
 * проверка сервисов и веб-интерфейсов;
 * базовый smoke test для Spark;
 * первый обзор того, где в стенде `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE.

docs/maintainer_guide.md

@@ -34,6 +34,7 @@
 | `spark/`, `trino/`, `jupyter/`, `ide/` | Конкретные runtime-конфиги и образы | Описание программы курса |
 | `README.md` | Верхнеуровневое объяснение репозитория, архитектуры и точек входа | Пошаговый student onboarding во всех деталях и low-level runtime reference |
 | `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей |
+| `docs/study_workflow.md` | Повседневный маршрут: продолжить и закончить занятие, сохранить результат, восстановиться после ошибки | Состав модулей, установка окружения с нуля |
 | `docs/stack_reference.md` | Технический reference стенда: сервисы, порты, доступ, reset, smoke-тесты | Роль основного onboarding-документа или описание всей программы курса |
 | `docs/course_prd.md` | Product scope, аудитория, learning outcomes, dataset strategy, out of scope | Технические мелочи запуска контейнеров |
 | `docs/course_program.md` | Модульная структура курса, состав материалов, checkpoints | Подробные docker-команды и legacy-лабы |
@@ -75,6 +76,7 @@
 
 - `START_HERE.md`;
 - `docs/course_program.md`;
+- `docs/study_workflow.md`;
 - соответствующие `notebooks/`;
 - `README.md`, если меняется верхнеуровневый вход в репозиторий.
 

docs/mentor_notes.md

@@ -17,9 +17,9 @@
 
 | Модуль | Тема | Самостоятельная работа | Обсуждение с ментором | Комментарий |
 | --- | --- | --- | --- | --- |
-| 1 | Вход в стенд | 30-40 мин | 10-15 мин | Если Docker знаком, идёт быстро |
+| 1 | Вход в стенд | 30-40 мин | 10-15 мин | Без учета первой сборки: ее время зависит от сети и компьютера |
 | 2 | Ментальная модель | 40-60 мин | 15-20 мин | Ключевой модуль; убедись, что студент заходил в MinIO |
-| 3 | Raw-данные | 40-50 мин | 10 мин | Зависит от скорости загрузки данных |
+| 3 | Raw-данные | Около 2 часов | 10 мин | Включая 20–30 минут на практику со Spark-сессией; датасет скачивается заранее |
 | 4 | Bronze + Iceberg | 60-80 мин | 15-20 мин | Первая таблица — много новых концепций |
 | 5 | Silver | 50-70 мин | 15 мин | Трансформации + проверки качества |
 | 6 | Spark + Trino | 40-60 мин | 15 мин | Если DBeaver настроен заранее — быстрее |
@@ -34,8 +34,9 @@
 
 ### Модуль 1. Вход в стенд
 
-- **Docker не хватает ресурсов.** Сверься с [требованиями в START_HERE](../START_HERE.md#prerequisites). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста.
-- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`.
+- **Docker не хватает ресурсов.** Сверься с [системными требованиями](../START_HERE.md#системные-требования). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста.
+- **После паузы виден старый вывод, но переменные пропали.** Разбери разницу между файлом ноутбука и ядром Python по [памятке учащегося](./study_workflow.md). Передай студенту ее до второго занятия; для обращения за помощью там есть список нужных сведений.
+- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps -a` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`.
 - **Студент не читает `START_HERE.md`.** Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу.
 
 ### Модуль 2. Ментальная модель

docs/stack_reference.md

@@ -20,14 +20,17 @@
 
 ## Основные команды
 
-Все команды выполняются из корня репозитория.
+Все команды выполняются в терминале хоста из корня репозитория.
+Для первого запуска и настройки прав используй [START_HERE](../START_HERE.md),
+для продолжения работы — [памятку учащегося](./study_workflow.md).
 
 ### Сборка и запуск
 
 ```bash
+docker compose pull minio minio-init postgres trino
 docker compose build
 docker compose up -d
-docker compose ps
+docker compose ps -a
 ```
 
 ### Логи
@@ -42,12 +45,36 @@ docker compose logs -f ide
 
 ### Остановка и reset
 
-```bash
-docker compose down
-docker compose down -v
-```
+| Действие | Команда | Что происходит с данными |
+| --- | --- | --- |
+| Пауза до следующего занятия | `docker compose stop` | Контейнеры остановлены, файлы и volumes сохранены |
+| Продолжение | `docker compose up -d` | Сервисы запускаются с прежними данными |
+| Удаление контейнеров и сети | `docker compose down` | Volumes и файлы на хосте сохраняются, состояние внутри удаленных контейнеров теряется |
+| Полный сброс учебных данных | См. [отдельную инструкцию](./study_workflow.md#начать-с-чистых-данных) | Удаляются MinIO volume и каталог PostgreSQL |
 
-`down -v` удаляет volumes и возвращает стенд в чистое состояние.
+Переменные Python и живые Spark-сессии после остановки нужно создать заново.
+
+## Ресурсы и проверенная среда
+
+Актуальный бюджет для учащегося приведен в
+[системных требованиях](../START_HERE.md#системные-требования).
+Он учитывает одновременную работу двух Spark worker-ов, драйвера в IDE, Trino,
+MinIO и PostgreSQL. У каждого worker-а в Compose указаны 2 CPU и 2 ГБ для
+приложений Spark; это не предел потребления всей JVM или контейнера.
+Потребление при простое не показывает пик во время урока.
+
+Проверка 19 октября 2026 года: Linux x86_64, Docker Engine, 6 CPU и около
+11,1 ГиБ памяти, видимых Docker. Выполнены первый ноутбук в Chromium и проверка
+Spark → Iceberg → Trino. Прогона всех восьми модулей с измерением пиков памяти
+и диска не было; минимальный объем RAM не установлен. Docker Desktop и ARM64
+в этой проверке не запускались.
+
+Размеры локально собранных образов на этой машине: Spark — около 3,37 ГБ,
+Jupyter — 3,72 ГБ, IDE — 4,90 ГБ. Jupyter включает слои Spark, IDE включает слои
+Jupyter: складывать эти три числа для оценки места неправильно. IDE добавляет
+около 1,18 ГБ. IDE вместе с отдельными образами Trino, PostgreSQL и MinIO дает
+около 8,1 ГБ до учета кэша сборки, данных и особенностей хранилища Docker.
+Поэтому перед первой сборкой нужен запас места сверх размера готовых образов.
 
 ## Доступ к сервисам
 
@@ -218,6 +245,7 @@ JupyterLab остаётся запасным интерфейсом. Он ред
 | `ide/Dockerfile` | code-server и расширения на базе образа Jupyter |
 | `ide/lakehouse.code-workspace` | папки рабочей области и настройки Python |
 | `docs/network_access.md` | источники образов и зависимостей, резервный registry и диагностика сети |
+| `docs/study_workflow.md` | повседневная работа, сохранение состояния и диагностика ошибок |
 
 ## Smoke-тесты
 
@@ -336,6 +364,7 @@ SELECT * FROM <table> FOR VERSION AS OF <snapshot_id>;
 
 - `README.md` — чтобы понять, что это за репозиторий и куда идти дальше.
 - `START_HERE.md` — чтобы впервые поднять стенд и пройти Модуль 1.
+- `study_workflow.md` — чтобы продолжить занятие, сохранить результат и разобраться с ошибкой.
 - `stack_reference.md` — чтобы быстро вспомнить порты, команды, точки доступа, шпаргалку и smoke-тесты.
 - `course_program.md` — чтобы понять учебную траекторию дальше первого модуля.
 - `glossary.md` — чтобы вернуться к определению термина (storage, catalog, compute, snapshot и др.).

docs/study_workflow.md

@@ -0,0 +1,153 @@
+# Как заниматься со стендом
+
+Для первой сборки используй [START_HERE](../START_HERE.md), для выбора урока —
+[маршрут по модулям](./course_program.md#маршрут-по-модулям). Эта памятка нужна,
+когда окружение уже готово.
+
+## Начать следующее занятие
+
+1. Запусти Docker и открой терминал хоста в той же папке репозитория.
+2. Выполни:
+
+   ```bash
+   docker compose up -d
+   docker compose ps -a
+   ```
+
+   Дождись `healthy` у `ide`, `trino` и `postgres-iceberg`. У двух init-контейнеров
+   нормальное состояние — `Exited (0)`. Повторять сборку перед каждым занятием
+   не нужно; она понадобится после изменения образов или зависимостей.
+3. Открой [VS Code в браузере](http://localhost:8889) и нужный ноутбук.
+   При запросе ядра выбери **Select Kernel → Python Environments → /usr/bin/python3**.
+4. После остановки стенда переменные Python нужно создать заново: выполни
+   импорты, создание Spark-сессии и подключений в начале текущего ноутбука.
+   Сохраненный вывод ячеек может быть виден еще до их запуска.
+5. Продолжи с места, на котором остановился. Перед повтором ячеек с записью
+   данных, `INSERT`, `CREATE OR REPLACE`, `DROP` или очисткой истории прочитай
+   пояснение: повторный запуск может изменить таблицу или создать новый snapshot.
+
+Используй прежнюю папку репозитория: имя Compose-проекта определяет, какие
+Docker volumes подключаются. После переименования папки или запуска с другим
+`-p` можно получить новый пустой набор данных вместо предыдущего.
+
+## Как проходить ноутбук
+
+Ноутбук состоит из пояснений и кодовых ячеек. Ядро Python выполняет код и хранит
+переменные в памяти. Spark-сессия связывает этот Python-процесс с кластером.
+
+- Прочитай пояснение, запусти ячейку через `Shift+Enter`, дождись окончания и
+  сравни результат с описанием. Следующая ячейка может использовать предыдущие
+  переменные, поэтому порядок важен.
+- В самостоятельном задании заполни `TODO` и проверь результат. **Run All**
+  запускает код, но не выполняет задание за тебя.
+- Checkpoint — вопросы и проверки в конце урока. Покажи результат в своем
+  стенде и объясни его своими словами перед переходом к следующему модулю.
+- Сохраняй изменения через **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`).
+  Файл ноутбука вместе с ответами и выводом записывается в `notebooks/` на хосте.
+- Перед следующим модулем выполни завершающую ячейку `spark.stop()`, если она
+  есть; иначе вызови `spark.stop()` после окончания вычислений. Это освобождает
+  ресурсы Spark для следующего приложения. Закрытие вкладки браузера само по
+  себе не останавливает вычисления.
+
+Держи одну активную Spark-сессию: если несколько ноутбуков одновременно занимают
+все ядра worker-ов, новое задание может ждать ресурсы. Для своих SQL/Python-опытов
+можно создать дополнительный ноутбук в папке **Ноутбуки**. `src/`, документация
+и конфиги в IDE доступны только для чтения; их меняют в копии репозитория на хосте.
+
+### Если нужно перезапустить ядро
+
+Сначала сохрани ноутбук. В верхней панели нажми **Restart** и подтверди перезапуск.
+Затем заново выполни импорты и создание Spark-сессии. Переменные Python исчезнут;
+файлы и записанные учебные таблицы сохранятся.
+
+Перезапуск нужен, например, после изменения адреса кластера в
+`spark/spark-defaults.conf` или после остановки Spark-сессии, с которой хочешь
+продолжить работу. Повторный `getOrCreate()` при живой сессии использует ее;
+подробнее это разбирается в Модуле 3.
+
+## Закончить занятие
+
+Сохрани ноутбук, дождись завершения вычислений и запиши для себя номер модуля
+и следующую ячейку. Затем в терминале хоста выполни:
+
+```bash
+docker compose stop
+```
+
+Контейнеры остановятся и освободят занятую ими оперативную память. Файлы
+ноутбуков, исходные данные и таблицы останутся. На следующем занятии используй
+`docker compose up -d` из начала этой памятки.
+
+## Что и где сохраняется
+
+Docker volume — хранилище вне файловой системы контейнера. В этом стенде два
+таких хранилища: `minio-data` с объектами и `postgres-data` с каталогом Iceberg.
+Имена volumes в Docker обычно имеют префикс Compose-проекта.
+
+| Что | Где находится | После `stop` или `down` без `-v` |
+| --- | --- | --- |
+| Код, ответы и сохраненный вывод ноутбуков | `notebooks/` на хосте; `/opt/work` и `/opt/course/notebooks` в IDE | Сохраняются |
+| Скачанные Parquet и CSV | `data/nyc_taxi/` на хосте; `/opt/data/nyc_taxi` в контейнере | Сохраняются |
+| Raw-файлы, данные и metadata-файлы Iceberg | Бакет `lakehouse`, volume `minio-data` | Сохраняются |
+| Записи каталога Iceberg | PostgreSQL, volume `postgres-data` | Сохраняются |
+| Переменные Python и живая Spark-сессия | Память процессов | Теряются; создай заново |
+| Настройки IDE, доверие рабочей области | Файловая система контейнера `ide` | При `stop` сохраняются; при удалении или пересоздании контейнера могут сброситься |
+
+`docker compose down` удаляет контейнеры и сеть проекта. Именованные volumes
+остаются, поэтому после `up -d` таблицы доступны снова. Для обычного окончания
+занятия достаточно `stop`. Поведение команд описано также в документации Docker:
+[stop](https://docs.docker.com/reference/cli/docker/compose/stop/),
+[down](https://docs.docker.com/reference/cli/docker/compose/down/).
+
+### Начать с чистых данных
+
+Этот шаг нужен только для осознанного повторного прохождения с пустым
+хранилищем. Он удалит оба volumes: raw-данные в MinIO, таблицы, их историю
+и записи каталога PostgreSQL. Сохраненные ноутбуки и скачанные файлы в `data/`
+на хосте останутся.
+
+```bash
+docker compose down -v
+docker compose up -d
+```
+
+После сброса в ноутбуках еще может быть старый вывод. Заново создай raw в
+Модуле 3, bronze в Модуле 4 и silver в Модуле 5, прежде чем продолжать модули,
+которые используют эти данные. Сброс не является способом исправить сеть
+или выбор ядра.
+
+## Если что-то не работает
+
+Все `docker compose` команды ниже выполняются в терминале хоста из корня
+репозитория. Имя сервиса для логов берется из колонки `SERVICE` в `ps`:
+например, `postgres`, хотя контейнер называется `postgres-iceberg`.
+
+| Симптом | Первая проверка | Что сделать дальше |
+| --- | --- | --- |
+| Docker не отвечает | `docker version`: есть ли раздел Server? | Запусти Docker; при `permission denied` проверь доступ своего пользователя к Docker |
+| Образ или зависимость не скачивается | Найди адрес источника и сервис в ошибке | Пройди [диагностику сети](./network_access.md) |
+| `port is already allocated` / `address already in use` | Какой порт занят, не запущена ли другая копия стенда? | Освободи нужный порт; [список портов](../START_HERE.md#порты-стенда) |
+| Сервис завершился, `unhealthy` или долго `starting` | `docker compose ps -a`, затем `docker compose logs --tail=100 <service>` | Для `postgres-iceberg` используй сервис `postgres`; проверь первую ошибку в логах |
+| VS Code не открывается | `docker compose ps -a ide`, логи `ide` | Дождись `healthy`, открой `http://localhost:8889`; для сервера используй [SSH-туннель](./stack_reference.md#vs-code-в-браузере) |
+| Ошибка notebook webview / service worker | Адрес в браузере и отдельная вкладка | Открой `http://localhost:8889`, без IP удаленного сервера и без встраивания в другой сайт |
+| Не выбирается ядро, нет `pyspark` | Рабочая область доверенная? Выбран `/usr/bin/python3`? | Повтори [выбор ядра](../START_HERE.md#как-работать-с-ноутбуками); детали в **View → Output → Jupyter** |
+| `NameError`, потерялась переменная | Ядро перезапускалось или выбран другой ноутбук? | Выполни импорты и подготовительные ячейки по порядку |
+| Spark долго ждет, `Initial job has not accepted any resources` | В Spark UI два worker-а `ALIVE`? Есть другие приложения в `Running Applications`? | Заверши свою предыдущую сессию через `spark.stop()`; проверь логи worker-ов |
+| Ядро умерло, контейнер убит, подозрение на память | `docker stats --no-stream`, лимит памяти Docker/WSL2 | Сверь [системные требования](../START_HERE.md#системные-требования), закрой другие вычисления; одного кода 137 недостаточно для вывода об OOM |
+| Ноутбук не сохраняется (`Permission denied`) | Это файл в папке **Ноутбуки**? Совпадает UID? | Проверь `.env` и [настройку прав перед сборкой](../START_HERE.md#быстрый-запуск); после изменения UID/GID повтори `docker compose build`, затем `docker compose up -d` |
+| Нет файлов Taxi или таблицы из прошлого модуля | Файлы в `data/nyc_taxi`, предыдущие модули, прежняя папка проекта | Для raw нужен Модуль 3, для bronze — 4, для silver — 5; после сброса восстанови их по порядку |
+
+### Что передать ментору
+
+Укажи ОС, модуль, ячейку или команду, ожидаемый результат и полный текст ошибки.
+Приложи вывод:
+
+```bash
+docker compose version
+docker compose ps -a
+docker compose logs --tail=100 ide
+```
+
+В последней команде замени `ide` на проблемный сервис, если ошибка в другом компоненте.
+Для ошибки ноутбука добавь выбранный путь Python и вывод ячейки. Пароли, токены
+и адреса прокси с учетными данными в сообщение не включай.