docs: session handoff — APK launches old UI despite new build

Author: claude

SESSION_HANDOFF.md

@@ -0,0 +1,99 @@
+# Передача контекста следующей сессии Claude Code
+
+## Проект
+**Black Castle Dungeons** — текстовая RPG-игра на Kivy/KivyMD для Android.
+Репозиторий: `samvelkoch/black-castle-dungeons`
+Рабочая ветка: `claude/fix-apk-assets-MIoQY`
+
+---
+
+## Что делал в этой сессии
+
+### Исходная проблема
+Пользователь хотел получить рабочий APK с новым Material Design UI (KivyMD), но при запуске APK на телефоне открывалась **старая версия игры** (без MD).
+
+### Что было сделано
+
+1. **Переход на KivyMD UI**
+   - Основной файл с MD интерфейсом: `android_app/main_md.py`
+   - Старый UI: `android_app/main.py`
+   - В `buildozer.spec` точка входа прописана как `main_md.py` (через `source.main` или просто `main.py` — НУЖНО ПРОВЕРИТЬ)
+
+2. **CI через GitHub Actions**
+   - Файл: `.github/workflows/build-apk.yml`
+   - Сборка через Docker: `kivy/buildozer:latest`
+   - Артефакт переименован в `BLACK-CASTLE-MD-v2-run${{ github.run_number }}`
+   - Триггеры: `master`, `feature/material-design`, `claude/**`
+
+3. **Пины зависимостей в buildozer.spec**
+   - `requirements = python3,kivy==2.3.1,kivymd==1.2.0,...`
+   - Пинуем KivyMD 1.2.0 (не 2.x) — там другой API
+
+4. **Исправления совместимости KivyMD 1.2.0**
+   - Убраны импорты: `MDDivider`, `MDScrollView`, `MDSnackbar`, `MDTopAppBar`
+   - Убраны виджеты недоступные в 1.2.0
+
+---
+
+## НЕРЕШЁННАЯ ПРОБЛЕМА (главная!)
+
+**Симптом:** APK собирается успешно (Actions зелёный), пользователь скачивает и устанавливает APK, но на телефоне запускается **старый UI без Material Design**.
+
+### Гипотезы (что надо проверить)
+1. **Docker кэш дистрибутива** — в образе `kivy/buildozer:latest` может быть встроенный кэш python-for-android дистрибутива с именем `dungeonblackcastle`. В логе сборки видно:
+   ```
+   All possible dists: [<Distribution: name dungeonblackcastle with recipes...>]
+   dungeonblackcastle has compatible recipes, using this one
+   ```
+   Buildozer находит готовый дистрибутив и **не пересобирает его**, поэтому APK содержит старый Python-код.
+
+2. **Точка входа в buildozer.spec** — возможно `main.py` (старый файл) всё ещё прописан как главный, а не `main_md.py`.
+
+3. **Файлы не попадают в APK** — assets или `.py` файлы могут исключаться через `source.exclude_patterns`.
+
+### Что нужно попробовать
+- [ ] Добавить `buildozer android clean` перед сборкой в workflow
+- [ ] Или передать флаг чтобы не использовать кэшированный дистрибутив
+- [ ] Проверить в `buildozer.spec` что `source.main = main_md.py` (или что `main_md.py` переименован в `main.py`)
+- [ ] Добавить в начало `main_md.py` явный print/лог версии, потом проверить `adb logcat` — что реально запускается
+
+---
+
+## Ключевые файлы
+
+| Файл | Назначение |
+|------|-----------|
+| `android_app/main_md.py` | Новый MD UI (KivyMD) — должен быть точкой входа |
+| `android_app/main.py` | Старый UI (Kivy без MD) |
+| `android_app/buildozer.spec` | Конфиг сборки Android |
+| `android_app/engine.py` | Игровой движок (общий для обоих UI) |
+| `android_app/sections.json` | Данные параграфов игры |
+| `android_app/assets/` | Картинки, шрифты |
+| `.github/workflows/build-apk.yml` | CI для сборки APK |
+
+---
+
+## Текущее состояние buildozer.spec (важные строки)
+```ini
+title = Black Castle Dungeons
+package.name = dungeonblackcastle
+package.domain = org.test
+source.dir = .
+source.include_exts = py,png,jpg,kv,atlas,json,ttf
+requirements = python3,kivy==2.3.1,kivymd==1.2.0,android
+# ПРОВЕРИТЬ: какой файл является точкой входа?
+# По умолчанию buildozer ищет main.py
+# Если точка входа main_md.py — нужно либо переименовать его в main.py,
+# либо прописать явно
+```
+
+---
+
+## Совет для следующей сессии
+
+1. Прочитай `android_app/buildozer.spec` целиком
+2. Убедись что точка входа — `main_md.py` (или что он переименован в `main.py`)
+3. Добавь `buildozer android clean` в workflow перед `buildozer android debug`
+4. Пересобери и проверь через `adb logcat` что реально запускается
+
+Удачи!