Imported from reziarlleh/KinogoATV (AGENTS.md). Install upstream with npx skills add reziarlleh/KinogoATV. Copyright stays with the author.

Инструкции для ИИ-агентов

Этот файл обязателен для любого агента, который меняет KinogoATV.

С чего начинать

1. Прочитать docs/README.md.
2. Прочитать docs/PROJECT_STATE.md и docs/ARCHITECTURE.md.
3. Для интерфейсной, сетевой, авторизационной или playback-задачи открыть соответствующий документ из индекса docs/README.md. Компоновка, цвета, TV-брендинг и D-pad-фокус определены в docs/UI_DESIGN.md.
4. Проверить git status -sb и не затрагивать посторонние пользовательские изменения.

Обязательные инварианты

• Приложение предназначено только для Android TV и горизонтального экрана, минимум Android 9 (API 28). Все основные действия должны быть доступны обычным D-pad-пультом без аэромыши.
• Это нативный каталог и Media3-плеер, а не WebView-оболочка сайта. Provider WebView допустим только как явный изолированный fallback для проверенного источника.
• Домены сервиса заменяемы. В моделях и хранилищах нельзя связывать контент с абсолютным доменом, если достаточно стабильного ID и относительного пути.
• Нельзя отключать HTTPS/public-DNS/SSRF-проверки ради «починки» источника или зеркала.
• Нельзя сохранять, логировать или включать в исключения transient media URL, iframe URL с токенами, cookies, пароль пользователя либо содержимое DataStore.
• Пароль пользователя должен сохраняться на устройстве, но только через существующий AndroidKeystoreCredentialCipher; это осознанное продуктовое требование.
• Статус «Не смотрел» означает удаление взаимоисключающего статуса из серверных закладок. Независимое «Избранное» при этом не меняется.
• Нельзя запускать connectedDebugAndroidTest на пользовательском телевизоре: Gradle managed install/uninstall может удалить установленное приложение и его данные. Для точечного instrumentation-теста использовать ручную установку test APK и удалять только пакет com.kinogo.atv.test.
• Не подключаться к реальному TV через ADB, не устанавливать APK и не выполнять аппаратный smoke без предварительного явного разрешения владельца на конкретный узкий сценарий. Запрашивать такую проверку только когда результат нельзя надёжно установить код-ревью и автоматическими тестами.
• Не выполнять pm clear, uninstall com.kinogo.atv или очистку всего DataStore без прямого разрешения пользователя. Тестовые записи удалять адресно через соответствующий store.
• Сборка APK не доказывает работу плеера и пульта. Изменения воспроизведения, фокуса и media keys требуют проверки на реальном TV либо должны быть явно отмечены как непроверенные.
• .signing/kinogo-tv-dev.keystore не коммитится. Потеря этого ключа лишит возможности обновлять уже установленное приложение.

Документация является частью Definition of Done

При любом изменении поведения до завершения задачи обновить:

• docs/CHANGELOG.md — что изменилось;
• docs/PROJECT_STATE.md — если изменилось текущее состояние, версия или доказательства;
• README.md — только если изменилась доступная пользователю функция или порядок использования;
• docs/ROADMAP.md — если пункт реализован, отменён или переприоритизирован;
• профильный документ (ARCHITECTURE, UI_DESIGN, SERVICE_INTEGRATION, PLAYBACK, SECURITY, TESTING, RELEASE_PROCESS, DECISIONS) — если изменился его контракт.

Не добавлять в пользовательский README.md планы, отвергнутые идеи и внутренние ограничения. Они хранятся в docs/.

Документация как память и система отката

Документация должна позволять восстановить ход разработки без доступа к старому чату.

• docs/PROJECT_STATE.md всегда указывает текущий known-good commit/tag, APK hash, устройство и проверенные подсистемы.
• docs/CHANGELOG.md хранит хронологию изменений; исправленную проблему не удалять из истории.
• docs/REGRESSION_LOG.md хранит симптом, окружение, affected/last-known-good версии, первопричину, исправление и защитный тест.
• Перед рискованной переработкой создать либо записать точку отката: commit/tag и набор зелёных проверок. Нельзя начинать широкий рефакторинг с неизвестно сломанного baseline.
• При новом сбое сначала определить последний подтверждённо рабочий baseline и диапазон изменений после него, затем менять код.
• Если точная причина старого сбоя неизвестна, так и записать; не заменять пробел догадкой.
• После исправления регрессии добавить автоматическую проверку там, где это возможно, и связать её с записью regression log.
• В handoff обязательно указывать baseline/rollback point, изменённые подсистемы и то, какие проверки ещё не повторялись.

Проверка

Минимальный набор для обычного изменения:

.\gradlew.bat testDebugUnitTest lintDebug assembleDebug `
  --no-daemon --max-workers=1 `
  '-Pkotlin.compiler.execution.strategy=in-process'

Перед запуском требуется JDK 17 и Android SDK. Для release либо установки поверх пользовательской stable-signed версии дополнительно нужен отдельный signing key; чистый clone может собирать обычный debug APK стандартным Android debug key. Полный процесс описан в docs/DEVELOPMENT.md и docs/TESTING.md.