# Инструкции для ИИ-агентов Этот файл — единственный авторитетный набор агентских правил для проекта `ExchangerThemeDlcBuilder`. Перед любым изменением прочитайте его полностью. ## Назначение и границы проекта - Проект создаёт, проверяет, показывает и собирает внешние PCK-темы Exchanger. - Рабочая область агента по умолчанию ограничена этой папкой. Соседний проект Exchanger можно читать для сверки host-контракта, но нельзя менять без отдельного явного поручения пользователя. - Код бизнес-логики, оплаты, COM-контроллера и настроек автомата принадлежит Exchanger. Темы считаются доверенными и могут содержать собственную GDScript-логику визуальных и вспомогательных runtime-компонентов, но прямые зависимости от внутренних узлов host нужно документировать. - Перед изменениями прочитайте [README.md](README.md), [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md) и профильный документ из [docs/README.md](docs/README.md). Для сцен обязательно прочитайте [docs/BINDING_CONTRACT.md](docs/BINDING_CONTRACT.md). ## Обязательная долговременная память - MCP-сервер `agentmemory` используется постоянно. Канонический project id: `exchanger-theme-dlc-builder`. - Первое действие с инструментами в каждой задаче — `memory_recall` или `memory_smart_search` по затрагиваемой подсистеме. Повторите поиск перед работой с незнакомой частью проекта или при противоречии памяти и файлов. - После каждого устойчивого открытия, решения, изменения архитектуры/контракта/структуры, найденной ошибки и законченного блока QA сохраняйте атомарную запись через `memory_save`. - Записывайте назначение файлов, связи, команды и фактические результаты проверок, а не сырые логи. Репозиторий и свежий запуск имеют приоритет над устаревшей памятью. - Перед финальным ответом обязательно сохраните итоговое состояние, изменённые файлы, проверки и незакрытые вопросы. При делегировании передайте подагенту эти же требования. ## Godot и инструменты - **Ziva-Godot категорически запрещён без исключений.** Нельзя использовать сервер, tools, plugins, skills, ресурсы или документацию с этим именем даже для чтения и диагностики. - Для Godot Editor разрешён только MCP-сервер `godot-ai`. Перед работой со сценами проверьте сессию, сведения о проекте, открытую иерархию и журнал. Если `godot-ai` недоступен, используйте безопасные shell-команды и файловое редактирование, но не Ziva-Godot. - Текстовые файлы меняйте точечно через `apply_patch`. Не перезаписывайте пользовательские файлы shell-трюками и не запускайте форматирование всего проекта без необходимости. - Сохраняйте чужие и незавершённые изменения. Перед удалением, переносом или массовой генерацией точно проверьте цель. `themes//package/` является единственным исходником и не должен очищаться неявно. Постоянного корневого staging-каталога нет. ## Неподвижные правила темы - Целевой формат preview: `720×1280`, портретная ориентация. - Внутри тематических сцен разрешены обычные возможности Godot: GDScript, сигналы, анимации, шейдеры, частицы, аудио, видео и процедурные визуальные эффекты. - Production-содержимое — только `themes//package/`. `source/`, references и preview tooling не должны попадать в PCK. Канонический namespace `res://exchanger_theme_dlc/` создаётся только внутри изолированного временного build-workspace и готового PCK. - Все девять production-сцен имеют канонические пути/имена/root metadata из manifest v2. - Production-сцены и их вложенные сцены могут содержать доверенный GDScript и любые необходимые Godot-узлы, включая `Timer`, `AudioStreamPlayer*` и `HTTPRequest`. Скрипты темы исполняются и в preview, и после инстанцирования PCK в Exchanger. - Каждый обязательный элемент содержит уникальный `exchanger_binding_id`, точный тип и ID из `contracts/screen_bindings.v2.json`. Каталог v2 содержит 9 экранов и 481 биндинг; его package-копия должна совпадать байт-в-байт. - При любом добавлении, удалении, переименовании или изменении binding ID, пути, типа, fallback, структуры binding-каталога либо правил разрешения биндингов обязательно в рамках той же задачи обновите `E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder\docs\BINDING_CONTRACT.md`. Изменение биндингов не считается завершённым, пока документ не соответствует фактическому контракту и не проверен вместе с `contracts/screen_bindings.v2.json` и host-контрактом Exchanger. - Production-сцена владеет каждым визуальным узлом, включая состояния Home, кнопки готовых сумм и фиксированные строки настроек. Exchanger не должен добавлять, удалять, переносить или стилизовать `Control` внутри внешнего ThemeView: host только находит существующие узлы, подключает сигналы и обновляет значения/видимость/доступность. - SETTINGS содержит заранее созданные скрытые панели текстовой и цифровой экранных клавиатур. Host может менять подписи/видимость/доступность клавиш и подключать сигналы, но не создаёт и не перестраивает их визуальное дерево. - SETTINGS также содержит theme-owned раздел «Сервис» и скрытый диалог учёта жетонов. Заголовки обоих хопперов имеют отдельные binding-id для точных остатков. Host меняет только остатки, тексты, видимость/доступность и подписывает кнопки; создавать или перестраивать эти элементы в runtime запрещено. - Видимый русский текст должен быть естественным и понятным владельцу автомата. Используйте «промо» и «промо-ролик», не «реклама». Внутренние English identifiers не переименовывайте. ## Рабочий цикл 1. Восстановите контекст из agentmemory и документов. 2. Активируйте нужную тему: `./activate-theme.ps1 -ThemeId `. 3. Меняйте `themes//package/` напрямую; preview загружает эти же файлы без промежуточной копии. 4. Проверяйте binding overlay и все девять вкладок preview в `720×1280`; сохраняйте статический фон и центрирование содержимого. 5. Выполните `./tools/Test-PackagedBindingContract.ps1`, затем `./test-theme.ps1 -ThemeId `. 6. Соберите `./build-theme.ps1 -ThemeId `. Установка в пользовательский каталог Exchanger — отдельное внешнее изменение и выполняется только когда оно входит в поручение. 7. Через `godot-ai` проверьте preview и runtime-журнал. При изменении host-контракта отдельно проверьте PCK в Exchanger. 8. Обновите относящиеся к изменению docs и agentmemory. ## Делегирование и критерии готовности - Делегируйте только независимые, чётко ограниченные задачи. Укажите рабочую папку, запрет Ziva-Godot, обязательную память, допустимые файлы и проверки. Не позволяйте нескольким агентам одновременно править одни и те же файлы. - Задача готова, когда исходники находятся в правильной теме, contract check и validator проходят, preview smoke и визуальная проверка девяти экранов не выявляют ошибок, production PCK не содержит builder tooling/референсов, документация соответствует фактам, а результат сохранён в памяти.