[2026-09-26] eagle: family/how-to/jellyfin-config.md personal/plans/balda-mm-pr-plan.md personal/tech/music-tags-repair-truenas.md

family/how-to/jellyfin-config.md

@@ -128,12 +128,16 @@ sqlite3 jf-copy.db "SELECT Name, AccessToken FROM ApiKeys;"
 
 > ⚠️ **Структура папок НЕ соответствует музыкальной раскладке** (`Artist/Album`). Jellyfin для `collectionType=music` раскладывает по **тегам**, а не по папкам. Категории вида `!Rock&Folk` — «мусорные» имена из файловой системы, не артисты. Ожидаемый риск: файлы с пустыми тегами уедут в `Unknown Artist`. Вариант митигации — `EnableFolderView` в настройках библиотеки (даёт навигацию по физическим папкам).
 
-> 🔴 **ПОДТВЕРЖДЕНО ФАКТОМ 2026-09-26: теги массово битые.** Полная инвентаризация (7906 файлов,
-> `ffprobe`) дала точные цифры: `partial` 2919, `mojibake` 2419 (**восстановимо точно, 98.3%
-> проверено**), `empty` 1010, `lost` 662 (**`\ufffd` — данные уничтожены, только перезапись из
-> имён**), `clean` 537, `probe_failed` 359. Полный разбор, план ремонта и CSV с предлагаемыми
-> исправлениями — [[personal/tech/music-tags-repair-truenas]]. **Пока теги не починены —
-> Music-библиотеку не создавать.**
+> 🔴 **ПОДТВЕРЖДЕНО ФАКТОМ 2026-09-26: теги массово битые.** Полная инвентаризация v2 (7906 файлов)
+> дала точные цифры: `partial` 2920, `mojibake` **2759**, `empty` 1026, `lost` 662 (**`\ufffd` —
+> данные уничтожены, только перезапись из имён**), `clean` 537, `corrupt` 2, `probe_failed` **0**.
+> Полный разбор, план ремонта и CSV с предлагаемыми исправлениями —
+> [[personal/tech/music-tags-repair-truenas]]. **Пока теги не починены — Music-библиотеку не создавать.**
+
+> 🔴 **ПИТФОЛЛ `ffprobe` (2026-09-26):** `ffprobe` **молча отдаёт пустые теги** для валидного
+> ID3v2.3 с битым фреймом (напр. `comment='eng'`) — `exit=0`, пустой JSON, без ошибки. Так было
+> потеряно 343 файла (Высоцкий и др.). Читать ID3 **напрямую из байтов** (`id3_direct.py`).
+> Детали — [[personal/tech/music-tags-repair-truenas]].
 
 > ✅ **Порядок работ (решение Alex 2026-09-26):** ремонт тегов → валидация Alex → удаление
 > `Music/backup/` → **только потом** создание Music-библиотеки. Бэкап кладётся в `Music/backup/`
@@ -167,7 +171,8 @@ curl -s -X POST -H "X-MediaBrowser-Token: $TOKEN" \
 > 🔴 **ПЛАН ПЕРЕСМОТРЕН 2026-09-26 (позже в тот же день).** Полная инвентаризация тегов
 > (7906 файлов) подтвердила массовую порчу метаданных: mojibake + уничтоженные теги.
 > **Решение Alex: сначала починить теги, потом создавать библиотеку.**
-> Текущая работа — [[personal/tech/music-tags-repair-truenas]] (этапы 1–2 готовы, ждём апрув по CSV).
+> Текущая работа — [[personal/tech/music-tags-repair-truenas]] (этапы 1–2 готовы в редакции v2,
+> ждём апрув по CSV; CSV v1 был отклонён Alex за неразобранные `probe_failed`).
 > Создавать `collectionType=music` на битых тегах бессмысленно: Jellyfin раскладывает музыку
 > по тегам, не по папкам — получится свалка `Unknown Artist`.
 

personal/plans/balda-mm-pr-plan.md

@@ -0,0 +1,68 @@
+# Balda — Mattermost connector: план подготовки PR в апстрим
+
+> Создан 2026-09-26. Статус: **в работе**.
+> Команда Alex: «Коммит текущего стейта и продолжай пока не стыдно будет открывать PR mattermost connector.
+> Со всеми поддерживаемыми фичами и тестами. Вперёд! Без вопросов и требующих апрува команд.»
+> Часть [[personal/projects/balda/balda-mm-delegation-plan]] (Фаза 2 → PR в апстрим).
+
+## Цель
+
+PR в `baldaworks/balda`: полный Mattermost-транспорт — все поддерживаемые фичи Балды,
+тесты, зелёные quality gates, доки. Ветка `feat/mattermost-channel`, 1 коммит уже есть
+(`004fda2f`), рабочий счёт — 11 изменённых + 21 новых файлов в worktree.
+
+## Что уже готово (не переделывать)
+
+- Пакет `channel/mattermost/` (client, locator_codec, inbound, adapter, media, ingress, formatting, presentation, mattermostfx) — закоммичен `004fda2f`, 40 файлов.
+- Все quality gates были зелёные на `004fda2f`.
+- 6 причин тишины найдены и устранены живым запуском на Kraken (см. `balda-kraken-mm-deploy.md`).
+- `handlersfx/mattermost_ingress.go` — написан в worktree, НЕ закоммичен.
+
+## Пробелы, найденные ревизией кода (2026-09-26, вечер)
+
+### P1 — дефекты, которые полезут в PR и подведут ревью
+
+| # | Дефект | Где | Почему важно |
+|---|---|---|---|
+| P1.1 | Возможен двойной транспортный префикс в `principal` | `actors/command/start/handler.go:~420` | Прошлый фикс был только в БД → дефект вернулся. В PR пойдёт сырой код |
+| P1.2 | `channel/mattermost/*_test.go` — **0 файлов** | `channel/mattermost/` | «Со всеми тестами» — сейчас только 2 теста в `cmd/balda`. Апстрим-транспорт zulip имеет ~4 тест-файла |
+| P1.3 | `handlersfx/mattermost_ingress.go` не покрыт тестами и не закоммичен | `handlersfx/` | Ядро интеграции, написанное «на веру» |
+| P1.4 | README / `docs/balda.md` не упоминают Mattermost | корень, docs/ | Требование `AGENTS.md`; осталось открытым из Фазы 2 |
+| P1.5 | `SendDraftPlain` — проверить, что edit-in-place покрыт | `adapter.go` | Отклонение от плана, надо подтвердить тестом |
+| P1.6 | `SendTyping` — no-op; в `ProgressPolicy` Typing:false | `adapter.go`, `inbound.go` | Проверить, что нет мёртвого кода (линтер уже проходил, но повторно) |
+
+### P2 — качество PR
+
+- Прогнать `go test -race ./...` на затронутых пакетах, отделить апстримные фейлы (`git stash`).
+- `golangci-lint`, `go-arch-lint` — перепроверить после новых файлов.
+- Конвенциональные коммиты, разбивка: transport code / wiring / tests / docs.
+- Убрать из дерева артефакты, которым в PR не место (`tools/mm-*.sh`, дельта-JSON) —
+  решить: в отдельный коммит с `tools/` или не пушить вовсе.
+
+## План работ (по шагам)
+
+1. **Зафиксировать базу.** `check` + `apply` всех дельт в worktree → `go build ./...`.
+2. **Починить P1.1** (двойной префикс) в коде `handler.go`.
+3. **Тесты транспорта** (`channel/mattermost/`): `locator_codec_test.go`, `inbound_test.go`, `adapter_test.go` (по образцу zulip, `httptest`-сервер для REST).
+4. **Тесты хендлера** (`handlersfx/mattermost_ingress_test.go`).
+5. **P1.4** — README + `docs/balda.md`.
+6. **Quality gates** — build / vet / golangci-lint / go-arch-lint / race-тесты.
+7. **Коммиты** — по смыслу, Conventional Commits.
+8. **Обновить Obsidian** — итог и что осталось.
+
+## Definition of Done
+
+- `go build ./...`, `go vet ./...` = 0.
+- `golangci-lint run` = 0 issues.
+- `go-arch-lint check --project-path .` = OK.
+- Тесты транспорта + хендлера зелёные, `-race`.
+- Ни одного дефекта из `balda-go-fx-pitfalls` в коде.
+- Доки описывают Mattermost.
+- Коммиты в `feat/mattermost-channel`, готово к `git push` и PR.
+
+## Связанные заметки
+
+- [[personal/projects/balda/balda-mattermost-connector]] — Фаза 2 (код)
+- [[personal/projects/balda/balda-kraken-mm-deploy]] — Фаза 3 (деплой)
+- [[personal/tech/balda-go-fx-pitfalls]] — fx-питфоллы + дельта-апплаер
+- [[personal/plans/balda-mm-endtoend-plan]] — сквозной путь

personal/tech/music-tags-repair-truenas.md

@@ -18,9 +18,124 @@ related:
 ---
 # Music Tags Repair — TrueNAS (7906 файлов)
 
-> **Статус: ЭТАПЫ 1–2 ЗАВЕРШЕНЫ (2026-09-26). CSV передан Alex на проверку. Правки файлов НЕ начаты.**
+> **Статус: ЭТАПЫ 1–2 ЗАВЕРШЕНЫ (2026-09-26), затем ПЕРЕДЕЛАНЫ после замечаний Alex. CSV v2 передан на проверку. Правки файлов НЕ начаты.**
 > Следующий шаг — апрув Alex по CSV, затем бэкап + применение.
 
+## 🔴 ПЕРЕДЕЛКА ЭТАПА 1–2 (2026-09-26, после замечаний Alex)
+
+Alex отклонил первую версию CSV: **«А чё за probe failed на большинстве? Походу ты чего-то не доделал. ДДТ — город без окон — явная хуйня предложена. Ты бы хоть постеснялся не проверив мне файл сувать!»**
+
+Замечания оказались **верны по всем пунктам**. Разбор и что сделано:
+
+| # | Замечание Alex | Что было не так | Фикс |
+|---|---|---|---|
+| 1 | «probe_failed на большинстве» | 359 файлов отданы **пустыми заглушками** `action=probe_failed` вместо разбора. Я выяснил, что там валидный ID3v2.3, и **остановился** | Написан прямой ID3-парсер (`id3_direct.py`), интегрирован в инвентарь как fallback |
+| 2 | «ДДТ — явная хуйня» | Ранний `if verdict == "probe_failed": continue` **до** логики вывода → файлы `ДДТ - Любовь.mp3` не получили artist/title из имени | Ранний выход **убран**, вывод из имён применяется ко всем |
+| 3 | «не проверив мне файл сувал» | Отдал CSV, не проверив сэмплы проблемных групп | Проверки прогнаны до выдачи (см. ниже) |
+
+### 🔑 ПРИЧИНА `probe_failed`: битый фрейм `comment='eng'`
+
+Все 343 файла — **валидный ID3v2.3**, у которого `ffprobe` молча возвращает **пустой набор тегов**.
+Причина — нестандартный/битый фрейм `comment` со значением `eng`. `ffprobe` спотыкается на нём
+и отдаёт пустоту, **не сообщая об ошибке** (`exit=0`, пустой JSON).
+
+**Теги там БЫЛИ и оказались обычным mojibake:** `Âëàäèìèð Âûñîöêèé` → `Владимир Высоцкий`.
+То есть 343 файла — не «особый случай», а пропущенный массовый mojibake.
+
+**Решение:** парсить ID3 напрямую из байтов файла, минуя `ffprobe`.
+
+```python
+# id3_direct.py — читает ID3v2 фреймы из файла
+# ENCODINGS = {0: latin-1, 1: utf-16 (BOM), 2: utf-16-be, 3: utf-8}
+# FRAMES = TIT2→title, TPE1→artist, TPE1→album_artist, TALB→album,
+#          TCON→genre, TDRC/TYER→date, TRCK→track, TPOS→disc
+```
+
+> 🔴 **МЕТОДИЧЕСКИЙ ВЫВОД: `ffprobe` — НЕ единственный источник. Молчаливый пустой
+> результат ≠ «тегов нет».** Всегда иметь fallback-парсер для ID3. Это уже вторая
+> ловушка `ffprobe` в проекте (первая — `wget`/SOCKS в доке TrueNAS).
+
+## Инвентаризация v2 — `tag_inventory2.py`
+
+Двухступенчатое чтение: сначала `ffprobe`, при пустом результате — прямой ID3-парсер.
+
+| Источник тегов | Файлов |
+|---|---:|
+| `ffprobe` | 6703 |
+| `no_tags` (тегов нет реально) | 860 |
+| **`id3_direct`** (был `probe_failed`) | **343** |
+| `realmedia` | 0 (оказались `.mp3` с тегом внутри) |
+
+**Результат v2 (7906 файлов):**
+
+| Вердикт | v1 | v2 | Δ |
+|---|---:|---:|---|
+| `partial` | 2919 | 2920 | +1 |
+| `mojibake` | 2419 | **2759** | **+340** ← те самые «probe_failed» |
+| `empty` | 1010 | 1026 | +16 |
+| `lost` | 662 | 662 | — |
+| `clean` | 537 | 537 | — |
+| `corrupt` (новый) | — | 2 | +2 |
+| `probe_failed` | 359 | **0** | ✅ **устранён** |
+
+> ✅ **`probe_failed` полностью устранён.** Новый вердикт `corrupt` — управляющие байты
+> в тегах (например `\x1d56=>ABL...` у `!Классика/Пахмутова`).
+
+## CSV v2 — итоговые цифры
+
+| Действие | v1 | v2 |
+|---|---:|---:|
+| `fix` | 4601 | **4961** |
+| `no_change` | 2946 | 2945 |
+| `probe_failed` | 359 | **0** |
+| `fixed_lost` (восстановлено из имён) | 0 | **662** |
+| `fixed_corrupt` | 0 | 2 |
+
+**Контрольные проверки перед выдачей (все пройдены):**
+
+| Проверка | Результат |
+|---|---|
+| U+FFFD в выходных значениях | **0** ✅ |
+| `fix` с пустым title | **0** ✅ |
+| `fix` с пустым artist | 8 (плоские папки, источника нет — законно) |
+| `TrackNN` в title | **0** ✅ |
+| Регресс-тесты | **32/32 PASS** ✅ |
+
+## ⚠️ РАЗБОР СЛУЧАЯ ДДТ (проверка «это не мой баг»)
+
+Файлы `!Retro/ДДТ - *.mp3` предложены с `album = Просвистела` для всех пяти.
+**Проверено сырыми тегами — это НЕ баг скрипта:**
+
+```
+ДДТ - Любовь.mp3          album='Ïðîñâèñòåëà'  track='06'  date='1999'
+ДДТ - Просвистела.mp3     album='Ïðîñâèñòåëà'  track='1'   date='1999'
+ДДТ - Что такое осень.mp3 album='Ïðîñâèñòåëà'  track='5'   date='1999'
+ДДТ - Дождь.mp3           album='Ïðîñâèñòåëà'  track='3'   date='1999'
+ДДТ - В последнюю осень   album='Ïðîñâèñòåëà'  track='04'  date='1999'
+```
+
+Альбом `Просвистела` **реально записан в тегах** всех пяти файлов — это сборник 1999 года
+(треки 1, 3, 4, 5, 6). Скрипт прочитал факт. Если Alex захочет — можно поставить album из
+имени папки вместо тега, но по умолчанию тег приоритетнее.
+
+**Было исправлено по ДДТ:** `Ëþáîâü` → `Любовь`, `ÄÄÒ` → `ДДТ` (раньше отдавались пустыми).
+
+### Проверка через `check_ddt_album.py`
+
+Скрипт печатает полный набор тегов каждого файла — так отличим «баг скрипта» от «так в файле».
+**Вывод: всегда проверять сырые теги конкретного файла прежде чем заявлять о баге.**
+
+### Разбор транслит-имён (добавлено)
+
+| Пример | Результат |
+|---|---|
+| `detskiy_hor_benassi_satisfaction.mp3` | `Detskiy Hor Benassi Satisfaction` |
+| `29 Benny_benassi_feat._farenheit-free_your_mind__on_the_floor.mp3` | artist=`Benny Benassi Feat. Farenheit`, title=`Free Your Mind (On The Floor)` |
+| `01-benassi_bros-make_me_feel.mp3` | artist=`Benassi Bros`, title=`Make Me Feel` |
+
+Приём `prettify_translit`: подчёркивания → пробелы + заглавные буквы. **Кириллицу не выдумывает**,
+применяется только когда других источников нет.
+
 ## Контекст
 
 Задача началась как «добавить папку музыки в Jellyfin», но разведка тегов показала, что папка
@@ -137,16 +252,20 @@ ssh truenas_admin@mallexxx.duckdns.org \
 
 **2377 из 2419 (98.3%) конвертируются без потерь.** Остальные 42 — требуют ручного просмотра.
 
-### `probe_failed` расшифрован (359 файлов)
+### `probe_failed` — РАЗОБРАН И УСТРАНЁН (v2)
+
+**Итог: `probe_failed` больше не существует (0 файлов).** Все 343 файла прочитаны прямым
+ID3-парсером (см. раздел «ПЕРЕДЕЛКА» выше). Результат разбора v1:
 
 | Что | Кол-во | Деталь |
 |---|---:|---|
-| Валидный **ID3v2.3** | 343 | Заголовок целый (`hdr_ok=True`), теги есть — `ffprobe` их не отдал по иной причине |
-| **RealMedia** (`00051607`) | 15 | Это не mp3 — `video/x-pn-realvideo` |
+| Валидный **ID3v2.3** | 343 | Заголовок целый, теги есть. `ffprobe` молчит из-за битого фрейма `comment='eng'`. **Прочитаны через `id3_direct`** |
+| **RealMedia** (`00051607`) | 15 | Помечались как RealMedia по заголовку, но оказались `.mp3` с ID3 внутри → в v2 ушли в `id3_direct` |
 | Без заголовка | 1 | — |
 
-> Вывод: `probe_failed` ≠ «файл битый». 343 файла структурно валидны, но остаются
-> без извлечённых тегов. **Не блокируют ремонт остальных** — разбираются отдельно.
+> 🔴 Изначальный вывод «343 файла структурно валидны, но остаются без тегов» был
+> **недоработкой**: файлы надо было прочитать другим способом, а не оставлять заглушкой.
+> **`probe_failed` ≠ «файл битый» И ≠ «нет тегов».**
 
 ### Защита от порчи: доля кириллицы в `fix_encoding`
 
@@ -186,9 +305,9 @@ if cyr < 2:                    # одна буква — совпадение
 
 | # | Шаг | Статус |
 |---|---|---|
-| 1 | **Инвентаризация** read-only: `ffprobe` по 7906 файлам → CSV `путь, теги, классификация` | ✅ **ГОТОВО** — [[#✅ РЕЗУЛЬТАТ ЭТАПА 1 инвентаризация завершена (2026-09-26)]] |
-| 2 | **CSV с предлагаемым исправлением** → Alex | ✅ **ГОТОВО** — `~/Downloads/music-tags/tag-fix-plan.csv` |
-| 3 | **Апрув Alex по CSV** → только после этого правки | ⏳ **ЖДЁМ** |
+| 1 | **Инвентаризация** read-only: `ffprobe` по 7906 файлам → CSV | ✅ **ГОТОВО (v2)** — `tag_inventory2.py`, `probe_failed`=0 |
+| 2 | **CSV с предлагаемым исправлением** → Alex | ✅ **ГОТОВО (v2)** — `~/Downloads/music-tags/tag-fix-plan.csv` |
+| 3 | **Апрув Alex по CSV** → только после этого правки | ⏳ **ЖДЁМ** (v1 отклонён, v2 отдан) |
 | 4 | **Бэкап** — копировать **только перезаписываемые** файлы в `Music/backup/` | ⏳ |
 | 5 | **Ремонт** — перекодировка mojibake + восстановление из имён путей + чистка мусора | ⏳ |
 | 6 | **Приёмка** — Alex слушает выборку | ⏳ |
@@ -224,18 +343,24 @@ if cyr < 2:                    # одна буква — совпадение
 
 | Файл | Что делает |
 |---|---|
-| `tag_inventory.py` | **Этап 1.** Обход `Music`, `ffprobe` по каждому файлу, классификация тегов (`clean`/`mojibake`/`lost`/`empty`/`partial`/`probe_failed`) → CSV. Путь к `ffprobe` через `FFPROBE` env (по умолчанию `ffprobe`) |
+| `tag_inventory.py` | **Этап 1 (v1, устарел).** Обход `Music`, `ffprobe` по каждому файлу → CSV. Только `ffprobe`, без fallback → дал 359 `probe_failed` |
+| `tag_inventory2.py` | **Этап 1 (v2, актуальный).** `ffprobe` + **прямой ID3-парсер как fallback**. Добавлена колонка `source` (`ffprobe`/`id3_direct`/`no_tags`), новый вердикт `corrupt`. `probe_failed` = 0 |
+| `id3_direct.py` | **Прямой парсер ID3v2** из байтов файла (минуя `ffprobe`). Поддержка ID3v2.2/2.3/2.4, кодировок 0–3, extended header. Используется как fallback и как отладочный инструмент |
 | `analyse_inventory.py` | Анализ CSV инвентаря: доли вердиктов, проверка обратимости mojibake, разбор `lost`/`probe_failed` |
-| `build_fix_plan.py` | **Этап 2.** Строит CSV с колонкой «предлагаемое исправление». Содержит `fix_encoding`, `clean_value`, `repair`, `split_artist_title`, `title_from_name`, `derive_from_path` |
-| `check_fix_plan.py` | Контроль качества плана: сколько U+FFFD на выходе (должно быть 0), сколько без title, сэмплы «до/после» по каждой категории |
+| `build_fix_plan.py` | **Этап 2 (v1, устарел).** Содержал ранний выход по `probe_failed` — из-за него ДДТ отдавались пустыми |
+| `build_fix_plan2.py` | **Этап 2 (v2, актуальный).** Ранний выход убран, `prettify_translit` добавлен. Содержит `fix_encoding`, `clean_value`, `repair`, `split_artist_title`, `title_from_name`, `derive_from_path`, `prettify_translit` |
+| `check_fix_plan.py` | Контроль качества плана: U+FFFD на выходе, пустые title/artist, сэмплы «до/после» по категориям |
 | `find_bad_titles.py` | Ищет недоработки: `TrackNN` в title, голые номера, пустой artist |
-| `test_encoding_guard.py` | **32 регресс-теста.** Защита от порчи корректного UTF-8 (`Björk`, `Saint-Saëns`, `Noël`) + проверка `split_artist_title` |
+| `check_ddt_album.py` | Печатает **полный набор сырых тегов** файлов по маске — для проверки «баг скрипта vs так в файле» |
+| `diagnose_probe_failures.py` | Анализ заголовков файлов, упавших в `probe_failed`: ID3-версия, `hdr_ok`, размеры |
+| `test_encoding_guard.py` | **32 регресс-теста.** Защита от порчи корректного UTF-8 (`Björk`, `Saint-Saëns`, `Noël`) + `split_artist_title` |
 
 | Артефакт | Где | Что |
 |---|---|---|
-| CSV-инвентарь | `/mnt/RED_2TB/storage/tmp/tag-inventory.csv` (NAS) → `~/Downloads/music-tags/tag-inventory.csv` (Mac) | 7906 строк, результат этапа 1 |
-| **CSV-план правок** | `~/Downloads/music-tags/tag-fix-plan.csv` (Mac) | **Отдан Alex 2026-09-26.** 4601 `fix` / 2946 `no_change` / 359 `probe_failed` |
+| CSV-инвентарь v2 | `/mnt/RED_2TB/storage/tmp/tag-inventory2.csv` (NAS) → `~/Downloads/music-tags/tag-inventory.csv` (Mac) | 7906 строк, колонка `source`, `probe_failed`=0 |
+| **CSV-план правок v2** | `~/Downloads/music-tags/tag-fix-plan.csv` (Mac, 2.2 МБ) | **Отдан Alex 2026-09-26.** 4961 `fix` / 2945 `no_change` / 0 `probe_failed` |
 | Копия БД Jellyfin | `/tmp/jf-copy.db` (Mac) | Для чтения API-ключа (см. `[[family/how-to/jellyfin-config]]`) |
+| Копия плана на NAS | `/tmp/tag-fix-plan.csv` (NAS) | Для запуска `id3_direct.py`/`check_ddt_album.py` с хостовым Python |
 
 ### Колонки `tag-fix-plan.csv`
 
@@ -269,6 +394,28 @@ if cyr < 2:                    # одна буква — совпадение
 - ⚠️ `alpine` без `ffmpeg` → инвентарь падает молча. Ставить `apk add --no-cache ffmpeg` первой строкой.
 - 🔴 **`execute_code` требует апрува** — Alex явно сказал: **«Без аппрува команды используй! Скрипты пиши»**. Писать исполняемое в файл (`write_file`) → запускать через `terminal`. Не инлайн.
 - 🔴 **Наивная перекодировка CP1251→Latin-1 портит корректный UTF-8** (`Saint-Saëns` → `Saint-Saлns`). Обязателен guard по доле кириллицы (см. выше).
+- 🔴 **`ffprobe` молча отдаёт ПУСТЫЕ теги** при битом фрейме внутри (напр. `comment='eng'`) — при `exit=0` и валидном JSON. Нельзя считать «пусто от `ffprobe`» доказательством отсутствия тегов. Нужен fallback-парсер ID3 (`id3_direct.py`).
+- 🔴 **Ранний `continue` по «нераспознанному» вердикту = потеря файлов.** Именно так 359 файлов ушли заглушками, а ДДТ — без artist/title. **Неизвестный вход обрабатывать общей логикой, а не пропускать.**
+- 🔴 **Нельзя отдавать пользователю вывод, не проверив сэмплы проблемных групп.** CSV v1 ушёл Alex без проверки `probe_failed` и `!Retro` — и был справедливо раскритикован. Проверка = прогон `check_fix_plan.py` + `find_bad_titles.py` + выборочный `check_ddt_album.py`.
+- ⚠️ **Правка скриптов только локально → `scp` заново.** `sed -i` на NAS применён быть не должен (была такая ошибка, исправлена).
+- ⚠️ **Кириллица в аргументах `ssh`-команд** может поднять tirith `confusable_text`. Держать русские пути внутри файла-скрипта.
+- ⚠️ **Долгий инвентарь — запускать в фоне** (`docker run -d`) и поллить статус, а не держать `for`-цикл ожидания дольше 600 с (таймаут foreground).
+
+### 🧠 ГЛАВНЫЙ ПРОЦЕССНЫЙ УРОК ЭТОЙ СЕССИИ
+
+Alex: **«Ты бы хоть постеснялся не проверив мне файл сувать!»**
+
+Порядок работы, который себя оправдал **после** исправления:
+
+1. Написать скрипт **в файле** (`write_file`) — не инлайн, не `execute_code`.
+2. Прогнать **автотесты** на краевых случаях (латиница с умляутами, дефисы, номера).
+3. Прогнать **контрольные проверки** на реальном выводе: U+FFFD, пустые поля, оставшийся мусор.
+4. **Посмотреть сэмплы «до/после» глазами** по каждой проблемной группе.
+5. Проверить **сырые данные конкретного файла**, прежде чем спорить «это баг / не баг».
+6. **Только потом** отдавать пользователю.
+
+Три бага были пойманы пунктами 3–4 **до** выдачи. Пункт 5 отличает «баг скрипта» от «так в файле» (случай ДДТ).
+**Заглушка `needs investigation` в отчёте — это не результат, а моя недоработка.**
 
 ### 🐞 Три бага, пойманные ДО выдачи CSV (файлы не пострадали)