docs: actualize README, architecture, requirements (v1.1)

README:
- processed/ tree now shows mcgill/ and user/ subdirs
- --style user -> --style H1K0 in quick-start prefix example
- pretrained.report.txt and finetuned.report.txt added to artifact tables

architecture.md (-> v1.1):
- remove stale music21 fallback mention from chord_parser section
- fix ChordDataset: on-demand loading, not eager; remove non-existent
  make_dataloader from public interface
- fix train function name: train_model -> train
- update logging description: report goes to .report.txt, not stdout
- note that scripts use max_seq_len=256 (sequences top out at 195 tokens)

requirements.md (-> v1.1):
- FT-12: update from unified script to pretrain.py + train.py pair

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

README.md

@@ -112,7 +112,9 @@ hamori/
 ├── data/
 │   ├── raw_user/                      .chord-файлы собственного корпуса
 │   ├── raw_external/                  публичные корпуса (McGill Billboard и др.)
-│   ├── processed/                     токенизированные .pt-файлы для обучения
+│   ├── processed/
+│   │   ├── mcgill/                    токенизированные .pt-файлы McGill (train/val)
+│   │   └── user/                      токенизированные .pt-файлы собственного корпуса
 │   └── holdout/                       отложенная выборка для итоговой оценки
 ├── src/
 │   ├── chord_parser.py                парсинг аккордовых символов
@@ -159,7 +161,7 @@ python scripts/generate.py \
 ```bash
 python scripts/generate.py \
     --checkpoint checkpoints/finetuned.pt \
-    --mode major --key C --style user --function verse --time 4/4 \
+    --mode major --key C --style H1K0 --function verse --time 4/4 \
     --prefix "Cmaj7 Am7 Dm7" \
     --output reports/samples/continuation.chord
 ```
@@ -266,6 +268,7 @@ python scripts/pretrain.py
 | `checkpoints/pretrained.pt`         | лучший чекпоинт (по val loss) |
 | `checkpoints/pretrained.log.csv`    | метрики по эпохам             |
 | `checkpoints/pretrained_curves.png` | график кривых train/val loss  |
+| `checkpoints/pretrained.report.txt` | сводный отчёт о прогоне       |
 
 Если обучение было прервано, повторно построить график и отчёт без
 повторного обучения:
@@ -282,7 +285,8 @@ python scripts/train.py
 
 Загружает `checkpoints/pretrained.pt` и дообучает на собственном корпусе
 (`data/processed/user/`). Сохраняет `checkpoints/finetuned.pt` и аналогичный
-набор артефактов (`finetuned.log.csv`, `finetuned_curves.png`).
+набор артефактов (`finetuned.log.csv`, `finetuned_curves.png`,
+`finetuned.report.txt`).
 
 Существенно более низкая скорость обучения (lr=1e-5 против 3e-4) и небольшое
 число эпох (15) предотвращают катастрофическое забывание закономерностей,

docs/architecture.md

@@ -229,7 +229,7 @@ reports/figures/, reports/metrics.json
 
 **Связи.** Используется модулем `tokenizer.py` для разбора аккордов внутри
 периода. Не имеет зависимостей внутри проекта, кроме стандартной библиотеки
-Python и опционально `music21` (как fallback для нетипичных написаний).
+Python.
 
 ### 3.2 `src/tokenizer.py`
 
@@ -304,12 +304,10 @@ Voicing внутри аккорда выполняется минимально
     длину последовательности.
   - `__getitem__` возвращает тензор токенов, обрезанный или дополненный
     паддингом до максимальной длины.
-- Функция `make_dataloader(dataset, batch_size, shuffle) -> DataLoader` —
-  удобная фабрика.
 
-**Ключевые соображения реализации.** Все `.pt`-файлы загружаются в память при
+**Ключевые соображения реализации.** При инициализации датасет собирает список
-создании датасета. Это допустимо при текущем размере данных (тысячи периодов
+путей к `.pt`-файлам; сами тензоры загружаются с диска по запросу в
-максимум) и существенно ускоряет обучение по сравнению с подгрузкой с диска.
+`__getitem__`. При текущем размере данных это не является узким местом.
 
 Паддинг выполняется специальным токеном `<PAD>` с индексом 2 в словаре.
 В функции потерь этот индекс игнорируется через параметр `ignore_index`.
@@ -350,7 +348,7 @@ Voicing внутри аккорда выполняется минимально
 
 **Публичный интерфейс.**
 
-- Функция `train_model(config: TrainConfig) -> Path` — основная точка
+- Функция `train(config: TrainConfig) -> Path` — основная точка
   входа. Возвращает путь к лучшему чекпоинту.
 - Dataclass `TrainConfig` с полями для всех гиперпараметров.
 
@@ -360,10 +358,12 @@ Voicing внутри аккорда выполняется минимально
 тот же код для предобучения и дообучения, различающихся только параметрами
 запуска (низкий learning rate, меньшее число эпох для дообучения).
 
-Логирование: после каждой эпохи в stdout выводится строка с номером эпохи,
+Логирование: после каждой эпохи строка с номером эпохи, тренировочной
-тренировочной потерей, валидационной потерей и валидационной перплексией.
+потерей, валидационной потерей и перплексией выводится через `logging.INFO`.
-Параллельно строка добавляется в CSV-лог. Лучший по валидационной потере
+Параллельно строка добавляется в CSV-лог (`<output>.log.csv`). По окончании
-чекпоинт сохраняется отдельно.
+прогона скрипты `scripts/pretrain.py` и `scripts/train.py` записывают сводный
+отчёт с полной таблицей метрик в текстовый файл (`<output>.report.txt`).
+Лучший по валидационной потере чекпоинт сохраняется отдельно.
 
 Ранняя остановка: если валидационная потеря не улучшается на протяжении N
 эпох (по умолчанию 5), обучение завершается досрочно.
@@ -472,12 +472,12 @@ key, prefix=None, temperature=1.0, top_p=0.9, max_tokens=300, seed=None)
 к обобщению. Рекомендуемая конфигурация:
 
 | Параметр                     | Значение                                                                                   |
-| ---------------------------- | ----------- |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
 | Число слоёв                  | 3                                                                                          |
 | Размерность модели (d_model) | 192                                                                                        |
 | Число голов внимания         | 6                                                                                          |
 | Размерность FFN              | 768                                                                                        |
-| Длина контекста              | 512 токенов |
+| Длина контекста              | 512 токенов (256 в скриптах обучения — последовательности McGill не превышают 195 токенов) |
 | Размер словаря               | 85                                                                                         |
 | Dropout                      | 0.1                                                                                        |
 
@@ -912,4 +912,7 @@ Python. Реализация возможна, но требует погруж
 
 ## 9. История изменений
 
+- **1.1** (2026-05-20) — актуализация: убрана ссылка на music21, исправлено
+  описание ChordDataset (on-demand загрузка), исправлено имя функции train,
+  добавлено описание report-файла, уточнена рабочая длина контекста (256).
 - **1.0** (2026-05-19) — первоначальная редакция документа.

docs/requirements.md

@@ -182,16 +182,15 @@ serialize` должна давать `.chord`-файл, эквивалентны
 - Контекстное окно: 512 токенов.
 - Связанные веса входного и выходного эмбеддингов.
 
-**ФТ-12.** Система должна предоставлять единый скрипт обучения, параметризуемый
+**ФТ-12.** Система должна предоставлять два высокоуровневых скрипта обучения:
-аргументами командной строки, поддерживающий:
 
-- Обучение модели с нуля (предобучение).
+- `scripts/pretrain.py` — предобучение на публичном корпусе McGill.
-- Дообучение существующей модели (fine-tuning) — через параметр инициализации
+- `scripts/train.py` — дообучение на собственном корпусе с инициализацией
-  весов из указанного чекпоинта.
+  весов из чекпоинта предобучения.
-- Настройку всех ключевых гиперпараметров через аргументы.
+
-- Установку случайного зерна для воспроизводимости.
+Оба скрипта имеют флаг `--skip-training` для повторного построения графиков и
-- Автоматический выбор вычислительного устройства (CPU/GPU) с возможностью
+отчёта без перезапуска обучения. Низкоуровневая параметризация (гиперпараметры,
-  принудительного задания.
+архитектурные параметры, устройство) доступна через `src/train.TrainConfig`.
 
 **ФТ-13.** В процессе обучения система должна:
 
@@ -464,4 +463,6 @@ serialize` должна давать `.chord`-файл, эквивалентны
 
 ## 8. История изменений
 
+- **1.1** (2026-05-20) — ФТ-12 обновлён: два скрипта (pretrain.py, train.py)
+  вместо единого универсального CLI.
 - **1.0** (2026-05-19) — первоначальная редакция документа.