docs: clarify learner workflow and resource requirements

README.md

@@ -63,17 +63,23 @@ graph TB
 
 ## С чего начать
 
-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. Продолжи по [маршруту из восьми модулей](./docs/course_program.md#маршрут-по-модулям).
+3. Между занятиями используй [памятку учащегося](./docs/study_workflow.md):
+   остановка, продолжение работы и диагностика.
 
-Краткий запуск из корня репозитория:
+Для одного учащегося рекомендуем компьютер с 16 ГБ RAM, не менее 4 CPU и
+10 ГБ памяти, доступных Docker, а также от 20 ГБ свободного места перед сборкой.
+Подробности и границы проверки — в [системных требованиях](./START_HERE.md#системные-требования).
+
+Краткий запуск из корня репозитория после подготовки по `START_HERE`:
 
 ```bash
 docker compose pull minio minio-init postgres trino
 docker compose build
 docker compose up -d
-docker compose ps
+docker compose ps -a
 ```
 
 MinIO скачивается готовым из GHCR, его версия и digest закреплены. Если какой-то
@@ -96,7 +102,8 @@ Python и venv не нужны. Оба интерфейса доступны т
 
 ## Документы для прохождения
 
-- [START_HERE.md](./START_HERE.md) — первый маршрут: prerequisites, запуск, диагностика.
+- [START_HERE.md](./START_HERE.md) — подготовка компьютера, запуск и первый результат.
+- [docs/study_workflow.md](./docs/study_workflow.md) — памятка для каждого занятия и помощь при ошибках.
 - [docs/course_program.md](./docs/course_program.md) — модульная структура и состав учебных материалов.
 - [docs/stack_reference.md](./docs/stack_reference.md) — порты, команды, конфиги, шпаргалка.
 - [docs/glossary.md](./docs/glossary.md) — справочник терминов (storage, catalog, compute, snapshot и др.).

START_HERE.md

@@ -1,39 +1,82 @@
 # START HERE
 
-Этот документ нужен для первого входа в курс: поднять стенд, проверить сервисы, открыть интерфейсы, выполнить базовый smoke test и подготовить локальный data bundle для следующих модулей.
+Здесь ты подготовишь окружение и выполнишь первое вычисление в Spark.
+К концу запуска в ноутбуке появится `Spark cluster smoke test passed.`, а результат
+сохранится в файле на твоем компьютере. Smoke test — короткая проверка, что
+основные компоненты работают вместе.
+
+Если стенд уже собран, открой [памятку для следующего занятия](./docs/study_workflow.md).
+Она объясняет, как продолжить работу, что сохраняется и куда смотреть при ошибках.
 
 ## Маршрут прохождения
 
-1. Проверить prerequisites.
-2. Собрать и поднять стенд.
-3. Убедиться, что контейнеры живы.
-4. Открыть основные UI.
-5. Открыть VS Code в браузере и выполнить `notebooks/01_environment_and_smoke_test.ipynb`.
-6. Перед Модулем 3 подготовить учебный датасет в `./data/nyc_taxi`.
-7. При проблемах использовать логи и шаги диагностики из этого документа.
+1. Подготовь Docker, ресурсы и локальную копию репозитория.
+2. Скачай образы, собери окружение и проверь запуск сервисов.
+3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления.
+4. Продолжи по [программе курса](./docs/course_program.md#маршрут-по-модулям).
 
-## Prerequisites
+Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится
+только перед Модулем 6. Для первого ноутбука их готовить не нужно.
 
-Нужно заранее установить:
+<a id="prerequisites"></a>
 
-- Docker;
-- Docker Compose 2.17+ с BuildKit (`docker compose version`);
-- современный браузер для UI;
-- свободные порты на хосте.
+## Что подготовить
 
-Рекомендуемые ресурсы хоста:
+- Docker с запущенным движком и Docker Compose 2.17+ с BuildKit.
+- Современный браузер; основной интерфейс курса — VS Code на `localhost:8889`.
+- Git для скачивания репозитория или его распакованную ZIP-копию.
+- Свободные порты из таблицы ниже и доступ к источникам образов и зависимостей.
 
-- не менее `4 vCPU`;
-- не менее `10 GB RAM`, иначе `Spark`, `Trino` и IDE могут стартовать нестабильно;
-- хотя бы `20 GB` свободного места под образы, кэш первой сборки и контейнеры.
+Команды ниже рассчитаны на Bash: терминал Linux/macOS или терминал Linux
+в WSL2 на Windows с включенной интеграцией Docker Desktop. Выполняй их на
+машине, где работает Docker. Терминал внутри браузерного VS Code для запуска
+`docker compose` не подходит.
 
-Python, Java, Jupyter и расширения VS Code устанавливаются при сборке Docker-образов.
-На хосте не нужно создавать venv или устанавливать Python-пакеты.
+### Системные требования
 
-Для первой сборки нужен доступ к внешним репозиториям. Если ты работаешь из РФ
-или сети с ограничениями, при ошибке скачивания используй
-[инструкцию по доступу к репозиториям](./docs/network_access.md): в ней есть
-резервный источник MinIO и отдельные шаги для Docker и сборки зависимостей.
+Ориентир для одного учащегося и основного набора Taxi за три месяца:
+
+| Ресурс | Рекомендация | Что проверить |
+| --- | --- | --- |
+| Процессор | Не менее 4 CPU, доступных Docker | В Docker Desktop/WSL2 может стоять меньший лимит |
+| Память Docker | Не менее 10 ГБ RAM | Это память для контейнеров, а не общий объем памяти компьютера |
+| Память компьютера | 16 ГБ RAM или больше | Оставь память ОС, браузеру и другим приложениям |
+| Свободное место | Не менее 20 ГБ перед первой сборкой; 30 ГБ с запасом | На диске Docker и в папке репозитория: образы, кэш сборки, исходные данные и таблицы |
+
+Это рекомендуемый бюджет, а не измеренный минимальный порог. Полный курс на
+машине с 8 ГБ RAM не проверен. В Docker Desktop проверь
+[лимиты ресурсов](https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources);
+для режима WSL2 лимиты задаются у виртуальной машины WSL2. Место внутри диска
+Docker и свободное место на диске компьютера — отдельные ограничения.
+
+С добавлением VS Code образ окружения вырос примерно на 1,2 ГБ относительно
+Jupyter; базовые слои у них общие. MinIO скачивается готовым, компилировать его
+не нужно. [Основания оценок и границы проверки](./docs/stack_reference.md#ресурсы-и-проверенная-среда).
+
+Python, Java, Jupyter и расширения VS Code устанавливаются при сборке образов.
+На компьютере не нужно создавать venv или устанавливать Python-пакеты.
+
+Для первой сборки нужен интернет. Если ты работаешь из РФ или сети с
+ограничениями, при ошибке скачивания используй
+[инструкцию по доступу к репозиториям](./docs/network_access.md). Она различает
+проблемы скачивания образов и зависимостей внутри сборки.
+
+### Проверка до сборки
+
+Открой терминал в папке репозитория — там, где лежит `docker-compose.yml`:
+
+```bash
+docker version
+docker compose version
+docker info --format 'CPUs={{.NCPU}} MemoryBytes={{.MemTotal}}'
+docker compose config --quiet
+```
+
+В `docker version` должны быть разделы Client и Server, версия Compose — не
+ниже 2.17. `docker info` показывает ресурсы, которые видит Docker; память дана
+в байтах (10 ГБ — примерно 10 000 000 000 байт). Последняя команда при успехе
+ничего не печатает. Если Docker не отвечает или конфигурация не читается,
+исправь эту ошибку до сборки.
 
 ## Порты стенда
 
@@ -53,14 +96,26 @@ Python, Java, Jupyter и расширения VS Code устанавливают
 
 Все команды выполняются из корня репозитория.
 
-На Linux пользователь контейнера должен иметь доступ к файлам ноутбуков. Если
-твой UID отличается от `1000`, перед сборкой задай его в текущем терминале:
+На Linux и в WSL2 проверь владельца файлов:
 
 ```bash
-export NB_UID=$(id -u) NB_GID=$(id -g)
+id -u
+id -g
 ```
 
-Для Docker Desktop на macOS и Windows обычно подходят значения по умолчанию.
+Это UID и GID — числовые идентификаторы пользователя и группы. В контейнере по
+умолчанию используются `1000` и `100`. Если значения отличаются, до сборки
+создай `.env` в корне репозитория и укажи `NB_UID` и `NB_GID` со своими числами.
+Например, для вывода `1001` и `1001`:
+
+```dotenv
+NB_UID=1001
+NB_GID=1001
+```
+
+Если `.env` уже есть, измени только эти строки, сохранив остальные настройки.
+Файл остается между занятиями. Образец — [`.env.example`](./.env.example).
+На macOS с Docker Desktop обычно подходят значения по умолчанию.
 
 ### 1. Скачать готовые образы и собрать окружение
 
@@ -71,7 +126,8 @@ docker compose build
 
 Первая команда проверяет загрузку готовых сервисов до сборки окружения.
 MinIO уже собран; для Spark, Jupyter и IDE первая сборка скачивает зависимости
-и может занять несколько минут. Повторная сборка использует кэш Docker.
+и зависит по времени от сети и компьютера. Дождись завершения без ошибок;
+не переходи к запуску после неудачной сборки. Повторная сборка использует кэш Docker.
 
 ### 2. Поднять стенд
 
@@ -82,33 +138,36 @@ docker compose up -d
 ### 3. Проверить статус контейнеров
 
 ```bash
-docker compose ps
+docker compose ps -a
 ```
 
 Ожидаемое состояние:
 
-- контейнеры `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`, `trino`, `jupyter`, `ide` находятся в состоянии `Up`, у `ide` появляется статус `healthy`;
-- однократные init-контейнеры вроде `minio-init` и `iceberg-catalog-init` могут завершиться после успешной инициализации.
+- `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`,
+  `trino`, `jupyter`, `ide` работают (`Up`); у `postgres-iceberg`, `trino` и `ide`
+  дождись `healthy`;
+- `minio-init` и `iceberg-catalog-init` заканчивают работу со статусом `Exited (0)`.
+  Это успешная разовая подготовка хранилища и каталога. `Exited (1)` и другой
+  ненулевой код требуют проверки логов.
+
+Флаг `-a` показывает и завершившиеся контейнеры. Сам по себе статус `Up` еще
+не доказывает, что вычисления работают: дальше проверим их в ноутбуке.
 
 ## Куда заходить после старта
 
-Открой в браузере:
+| Что открыть | Что должно быть видно |
+| --- | --- |
+| [Spark Master](http://localhost:8080) | Два worker-а в состоянии `ALIVE` |
+| [MinIO Console](http://localhost:9001) | После входа `minioadmin` / `minioadmin` виден бакет `lakehouse` — контейнер для файлов курса |
+| [VS Code](http://localhost:8889) | Слева папки **Ноутбуки**, **Примеры (только чтение)**, **Документация (только чтение)** |
 
-- `http://localhost:8080` для `Spark Master UI`;
-- `http://localhost:8090` для `Trino UI`;
-- `http://localhost:9001` для `MinIO Console`;
-- `http://localhost:8889` для `VS Code в браузере`.
+В [Trino UI](http://localhost:8090) для входа достаточно имени, например `student`;
+пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается.
+Чтение общих таблиц через Trino разберем в Модуле 6.
 
-Для входа в `MinIO Console` используй:
-
-- логин: `minioadmin`;
-- пароль: `minioadmin`.
-
-Если интерфейсы открываются, переходи в VS Code и запускай:
-
-```text
-notebooks/01_environment_and_smoke_test.ipynb
-```
+Этот маршрут предполагает Docker на твоем компьютере: `localhost` относится
+к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно
+в [инструкции по SSH-туннелю](./docs/stack_reference.md#vs-code-в-браузере).
 
 ## Роли сервисов в стенде
 
@@ -122,6 +181,9 @@ notebooks/01_environment_and_smoke_test.ipynb
 
 ## Как работать с ноутбуками
 
+Ноутбук — файл с пояснениями, кодом и сохраненным выводом. Ядро — процесс Python,
+который исполняет код и хранит переменные до остановки.
+
 1. Открой `http://localhost:8889` в отдельной вкладке браузера.
 2. Если сверху виден **Restricted Mode**, нажми **Manage → Trust** и закрой окно
    Workspace Trust. Подтверди доверие только к своей копии этого учебного
@@ -131,83 +193,60 @@ notebooks/01_environment_and_smoke_test.ipynb
    `/usr/bin/python3`. Он находится внутри контейнера `ide`, где уже есть
    зависимости курса. Пункт **Existing Jupyter Server** здесь не нужен.
 5. Запусти первую кодовую ячейку кнопкой слева или `Shift+Enter`, затем остальные
-   ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через `Ctrl+S`.
+   ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через
+   **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`).
 
 Терминал VS Code тоже работает внутри контейнера. Команды `docker compose`
 выполняй в терминале хоста, откуда запускал стенд.
 
-Файлы доступны в IDE так:
+### Как понять, что первый запуск прошел
 
-- `./notebooks` смонтирован в контейнер как `/opt/work`;
-- `./src` смонтирован read-only как `/opt/src`;
-- весь репозиторий доступен read-only в `/opt/course`; его папка `notebooks/`
-  доступна для записи, поэтому правки из IDE сохраняются на хосте;
-- `./data` смонтирован read-only как `/opt/data`;
-- `PYTHONPATH=/opt/src`, поэтому helper-скрипты из `src/` доступны для импорта в ноутбуках;
-- учебный data bundle для Модуля 3 доступен по пути `/opt/data/nyc_taxi`.
+В третьей кодовой ячейке первого ноутбука появится отчет, содержащий:
+
+```text
+Spark cluster smoke test passed.
+master_url=spark://spark-master:7077
+result_sum=499999500000
+expected_sum=499999500000
+```
+
+В отчете есть и другие строки; значения выше должны совпасть. Затем выполни
+самостоятельное задание: замени `TODO` в словаре `service_roles` ролями сервисов.
+Сам факт запуска ячейки с `TODO` не означает, что задание выполнено.
+
+В конце выполни ячейку `spark.stop()`, сохрани ноутбук и проверь, что его изменения
+видны в `notebooks/01_environment_and_smoke_test.ipynb` на хосте. После повторного
+открытия сохраненный вывод остается виден. Такой вывод — запись прошлого запуска;
+он не означает, что ядро Python и Spark-сессия продолжают работать.
+
+Правила запуска ячеек, перехода между модулями и сохранения данных собраны в
+[памятке учащегося](./docs/study_workflow.md).
 
 Запасной интерфейс — JupyterLab на `http://localhost:8888`. Файлы ноутбуков общие,
-а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и останови
-его ядро. Подключение с удалённой машины описано в
-[техническом reference](./docs/stack_reference.md#vs-code-в-браузере).
-
-Ноутбуки берут адрес кластера из
-[`spark/spark-defaults.conf`](./spark/spark-defaults.conf). Если изменил его,
-перезапусти ядро и заново создай Spark-сессию. Повторный запуск ячейки с
-`getOrCreate()` использует текущую сессию. При перезапуске ядра переменные Python
-сбрасываются, а учебные таблицы и файлы сохраняются.
+а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и заверши
+Spark-сессию через `spark.stop()`; не редактируй один файл в двух интерфейсах
+одновременно.
 
 ## Базовая диагностика
 
-### Посмотреть список контейнеров
+Начни с `docker compose ps -a` и логов проблемного сервиса, например:
 
 ```bash
-docker compose ps
+docker compose logs --tail=100 ide
 ```
 
-### Посмотреть логи конкретного сервиса
-
-```bash
-docker compose logs -f spark-master
-docker compose logs -f trino
-docker compose logs -f minio
-docker compose logs -f jupyter
-docker compose logs -f ide
-```
-
-### Типовые первые проверки
-
-- Ошибка скачивания образа или зависимостей: найди имя недоступного источника
-  в сообщении и открой [диагностику сети](./docs/network_access.md).
-- `Spark UI` не открывается: проверь `docker compose ps` и логи `spark-master`.
-- `Trino UI` не открывается: проверь `docker compose ps` и логи `trino`.
-- `JupyterLab` не открывается: проверь `docker compose ps` и логи `jupyter`.
-- VS Code не открывается: проверь `docker compose ps ide` и логи `ide`.
-- Вместо ноутбука ошибка webview/service worker: открой `http://localhost:8889`
-  в отдельной вкладке, без IP сервера и без встраивания в другой сайт.
-- Ядро не выбирается: убедись, что рабочая область доверенная, и выбери
-  `/usr/bin/python3` в **Python Environments**. Для подробностей открой
-  **View → Output → Jupyter**.
-- `MinIO Console` не открывается: проверь `docker compose ps` и логи `minio`.
-- smoke test падает из ноутбука: сначала убедись, что `spark-master` и worker-ы видны в `Spark UI`.
+Выбери свой симптом в [таблице диагностики](./docs/study_workflow.md#если-что-то-не-работает).
+При ошибке скачивания сразу открой [диагностику сети](./docs/network_access.md).
 
 ## Restart и reset
 
-### Мягкий перезапуск стенда
+Для обычной паузы используй `docker compose stop`, на следующем занятии —
+`docker compose up -d`. Порядок действий и последствия удаления контейнеров
+описаны в [памятке](./docs/study_workflow.md#закончить-занятие).
 
-```bash
-docker compose down
-docker compose up -d
-```
-
-### Полный reset с удалением данных
-
-```bash
-docker compose down -v
-docker compose up -d
-```
-
-Используй полный reset, если хочешь пройти практику заново с чистого состояния.
+Полный сброс удаляет учебные таблицы и каталог. Его команда вынесена в
+[отдельный раздел](./docs/study_workflow.md#начать-с-чистых-данных), чтобы не путать
+с окончанием занятия.
 
 ## Подготовка учебного датасета (перед Модулем 3)
 
@@ -216,6 +255,7 @@ docker compose up -d
 Скачай каноническое учебное подмножество `NYC TLC Yellow Taxi Trip Records`:
 
 ```bash
+mkdir -p data/nyc_taxi
 curl -fLo data/nyc_taxi/yellow_tripdata_2024-01.parquet \
   https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet
 curl -fLo data/nyc_taxi/yellow_tripdata_2024-02.parquet \
@@ -246,13 +286,12 @@ ls -lh data/nyc_taxi/
 - Зачем: в Модуле 6 можно работать с Trino через DBeaver параллельно с ноутбуком — привычный SQL-интерфейс.
 - Предусловие: DBeaver установлен (ссылка на [dbeaver.io/download](https://dbeaver.io/download/)). Необязателен — ноутбук работает без DBeaver.
 - Шаги: New Database Connection -> Trino. Host: `localhost`. Port: `8090`. Database/Catalog: `lakehouse`. Username: любая строка (напр. `student`). Password: пусто. Test Connection -> Finish.
-- Проверка: `SHOW SCHEMAS FROM lakehouse;`. Ожидаем: `bronze`, `default`, `information_schema`, `silver`.
+- Проверка: `SHOW SCHEMAS FROM lakehouse;`. После модулей 4–5 должны быть видны `bronze` и `silver`; до их прохождения этих схем может еще не быть.
 - Troubleshooting: стенд поднят? контейнер `trino` Up? порт 8090 свободен?
 
 ## Что делать дальше
 
-- пройти `notebooks/01_environment_and_smoke_test.ipynb`;
-- пройти `notebooks/02_lakehouse_mental_model.ipynb`;
-- подготовить data bundle по инструкции выше и пройти `notebooks/03_raw_ingest_and_first_read.ipynb`;
-- свериться с программой курса в `docs/course_program.md`;
-- после прохождения первых модулей переходить к следующим учебным материалам.
+После первого ноутбука открой [маршрут по модулям](./docs/course_program.md#маршрут-по-модулям).
+В нем есть ссылки на все восемь уроков и результат, который нужно получить
+перед переходом дальше. Для следующего занятия сохрани ссылку на
+[памятку учащегося](./docs/study_workflow.md).

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

notebooks/01_environment_and_smoke_test.ipynb

@@ -15,7 +15,7 @@
         "- подключиться к Spark-кластеру из ноутбука;\n",
         "- выполнить базовый smoke test;\n",
         "- сопоставить сервисы стенда с их ролями;\n",
-        "- знать первый маршрут диагностики через `docker compose ps`, логи и UI.\n"
+        "- знать первый маршрут диагностики через `docker compose ps -a`, логи и UI.\n"
       ]
     },
     {
@@ -25,9 +25,10 @@
       "source": [
         "## Перед стартом\n",
         "\n",
-        "Перед запуском этого ноутбука пройди шаги из `START_HERE.md`.\n",
+        "Если стенд еще не готов, выполни подготовку и запуск по [START_HERE](../START_HERE.md#быстрый-запуск).\n",
+        "Если возвращаешься после паузы, используй [памятку учащегося](../docs/study_workflow.md).\n",
         "\n",
-        "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps` и просмотр логов выполняются в терминале хоста; терминал браузерного VS Code работает внутри контейнера.\n",
+        "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps -a` и просмотр логов выполняются в терминале хоста; терминал браузерного VS Code работает внутри контейнера.\n",
         "\n",
         "Ожидаемое состояние перед началом:\n",
         "\n",
@@ -149,7 +150,7 @@
         "1. Открой `Spark UI`, `Trino UI`, `MinIO Console` и браузерный VS Code.\n",
         "2. Сопоставь каждый сервис с одной из ролей: `storage`, `catalog`, `compute`, `entrypoint`.\n",
         "3. Объясни, почему этот smoke test не должен работать в `local[*]` режиме.\n",
-        "4. На хосте выполни `docker compose ps` и посмотри, какие контейнеры должны быть в состоянии `Up`.\n",
+        "4. На хосте выполни `docker compose ps -a` и посмотри, какие контейнеры должны быть в состоянии `Up`.\n",
         "5. На хосте выполни `docker compose logs -f trino` или `docker compose logs -f spark-master`, чтобы посмотреть, где начинается первичная диагностика.\n"
       ]
     },
@@ -182,9 +183,13 @@
         "\n",
         "- стенд поднят и основные контейнеры живы;\n",
         "- `Spark UI`, `MinIO Console`, `Trino UI` и браузерный VS Code открываются;\n",
-        "- smoke test завершился успешно и вернул ожидаемый результат;\n",
+        "- smoke test напечатал `Spark cluster smoke test passed.` и `result_sum=499999500000`;\n",
         "- ты понимаешь назначение `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE;\n",
-        "- ты знаешь, что первый маршрут диагностики начинается с `docker compose ps`, `docker compose logs -f <service>` и проверки UI.\n"
+        "- ты знаешь, что первый маршрут диагностики начинается с `docker compose ps -a`, `docker compose logs -f <service>` и проверки UI.\n",
+        "\n",
+        "После последней ячейки `spark.stop()` сохрани ноутбук. Дальше — [Модуль 2](./02_lakehouse_mental_model.ipynb)\n",
+        "или [завершение занятия](../docs/study_workflow.md#закончить-занятие).\n",
+        "Все уроки собраны в [маршруте по модулям](../docs/course_program.md#маршрут-по-модулям)."
       ]
     },
     {