exchanger-themes/AGENTS.md

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

Этот файл — единственный авторитетный набор агентских правил для проекта
`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/<id>/package/` является единственным исходником и не должен
  очищаться неявно. Постоянного корневого staging-каталога нет.

## Неподвижные правила темы

- Целевой формат preview: `720×1280`, портретная ориентация.
- Внутри тематических сцен разрешены обычные возможности Godot: GDScript, сигналы, анимации,
  шейдеры, частицы, аудио, видео и процедурные визуальные эффекты.
- Production-содержимое — только `themes/<id>/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 <id>`.
3. Меняйте `themes/<id>/package/` напрямую; preview загружает эти же файлы без промежуточной копии.
4. Проверяйте binding overlay и все девять вкладок preview в `720×1280`; сохраняйте статический
   фон и центрирование содержимого.
5. Выполните `./tools/Test-PackagedBindingContract.ps1`, затем
   `./test-theme.ps1 -ThemeId <id>`.
6. Соберите `./build-theme.ps1 -ThemeId <id>`. Установка в пользовательский каталог Exchanger —
   отдельное внешнее изменение и выполняется только когда оно входит в поручение.
7. Через `godot-ai` проверьте preview и runtime-журнал. При изменении host-контракта отдельно
   проверьте PCK в Exchanger.
8. Обновите относящиеся к изменению docs и agentmemory.

## Делегирование и критерии готовности

- Делегируйте только независимые, чётко ограниченные задачи. Укажите рабочую папку, запрет
  Ziva-Godot, обязательную память, допустимые файлы и проверки. Не позволяйте нескольким агентам
  одновременно править одни и те же файлы.
- Задача готова, когда исходники находятся в правильной теме, contract check и validator проходят,
  preview smoke и визуальная проверка девяти экранов не выявляют ошибок, production PCK не содержит
  builder tooling/референсов, документация соответствует фактам, а результат сохранён в памяти.