preland/CLAUDE.md

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

Поручение 25.10.2026 — preland#21

Боевые цели теперь zoompixel.ru на основном сервере и zoomila.ru/zoomika.ru на двух REG.RU-хостингах. Владелец явно разрешил первоначальное размещение этих трёх целей; прежняя заморозка #4 для этой задачи снята. Единственный активный .online — zoomstage.online (stage). zoompixel.online, zoomika.online, zoomila.online отключены, каталоги убраны из рабочих FTP-папок с резервным сохранением; не включать без поручения. На обоих REG.RU-хостингах владельцу нужен SFTP или FTP; существующие доступы описаны в актуальном разделе README, пароли остаются в REG.RU. Доменные готовые SVG — в brands/, существующий runtime-config сохранять. Обычный автодеплой остаётся только на stage; новое поручение не включает production-автодеплой. При расхождении со старыми разделами ниже действует это датированное решение и задача #21.

Область действия — репозиторий preland/. Общие правила рабочей области находятся в AGENTS.md и CLAUDE.md; канонический процесс и каталог ролей — в общей политике. Этот файл и CLAUDE.md содержат одинаковые локальные правила; обновлять их вместе.

Перед работой

• Прочитать README.md, заметку проекта, а для выката — .gitea/workflows/deploy.yml и единственный config.json.
• Проверить состояние ветки и чужие изменения в preland/; изменения API сайта согласовать с его контрактом и инструкциями api/.

Локальные ограничения

• Преленд — PHP без фреймворка и сборки; Yii::t реализован локальной заглушкой i18n.php. Сохранять существующие компоненты и передачу меток трафика на сайт.
• Загрузка идёт на POST /api/images/public/create с file и случайным client_key, переход — через /api/images/public/claim?key=…. Ключ одноразовый, срок 30 минут; переход напрямую на /public/upscale не заменяет передачу владельца через claim.
• host задаёт сайт назначения; HTTPS необходим для crypto.randomUUID(). Не обходить серверные правила доступа к загрузке и результату обработки.
• Рабочий config.json на каждом хостинге настраивает владелец. Деплой не имеет права перезаписывать его значений. При появлении новой обязательной UTM workflow получает текущий хостовый конфиг и меняет только ключи, которые прямо согласованы в задаче. Иные значения, включая уже настроенные UTM, остаются байт-в-байт прежними. Для #274 bin/ensure-focus-config.php — явное исключение: он задаёт только новый focus=face (default и rnd). После каждого такого выпуска фактический stage-config следует забрать и зафиксировать в Git. requisites.html также живёт только на хостинге и не перезаписывается. Не создавать target-specific конфиги или config.json.example.
• Корневые числовые наборы примеров /N/ на zoomstage.online — редактируемый контент stage. Обычный push в staging должен исключать [0-9]+/ из SFTP-заливки: актуальные примеры нельзя перезаписывать Git-версией. Снимок можно сохранить в Git по задаче; #22 не требует этого для обычного изменения runtime-набора.
• Коммит в main запускает FTP-автодеплой на все цели workflow; откат через git revert также запускает выкат. Коммит, push и изменения хостинга — только по прямому поручению.
• Проверки кода и браузера проводить в Docker без установки ПО на хост. Проверка загрузки по боевому адресу вызывает реальную обработку; выполнять её только в согласованном окружении, не публиковать ключи загрузок и FTP-секреты.

План, журнал и база знаний ведутся в корне рабочей области по общим правилам. Ссылки на политику и документацию не подключают MCP и не дают разрешения на публикацию или выкат.

Актуальные ресурсы (21.10.2026, preland#11)

• Git main и staging содержат одно проверенное дерево. Источники: текущая zoomzilla.ru — два логотипа Zoomzilla, четыре PDF, favicon и реквизиты; zoomstage.online — все файлы наборов /1 и /2. История Git не переписывается; известная старая заглушка запрещена в рабочей поставке.
• release/assets.json фиксирует SHA-256 всех статических ресурсов (текстовые SVG/CSS/HTML/webmanifest нормализуют CRLF→LF). До выпуска выполнить девять tests/check-*.php, php bin/release-assets.php --check, --primary и --stage-sets https://zoomstage.online. Если источник изменился, сначала синхронизировать актуальные файлы и manifest по задаче, затем повторить проверки. Не отключать guard ради выката.
• --primary читает именно текущую страницу основного сайта и проверяет её актуальные URL/реквизиты: старый сохранённый asset URL не доказывает актуальность. Новые логотипы должны пройти визуальную проверку обеих тем/шапки/подвала. Cache version в components/asset-url.php зависит от содержимого.
• По прямому выбору владельца21.10 requisites.html теперь входит в каноническую поставку. Единственное новое разрешённое изменение runtime-config — ключ requisites из release/requisites.json через bin/ensure-requisites-config.php; остальные байты полей сохраняются, повторный запуск ничего не меняет. Это явное исключение к прежнему host-only правилу реквизитов, а не разрешение заменять весь config.json. Git config.json хранит согласованный снимок; после выпуска сверять runtime в памяти, не сохранять потенциальные секреты в логи.
• /N/ не перезаписывается кодовой доставкой. Требование #11 о сверке runtime-наборов с Git заменено решением #22 от 25.10.2026 (см. ниже).
• SFTP берёт положительный список из bin/release-assets.php --files: никакие tests/bin/release/plans не публикуются. Старые известные служебные файлы удаляются только по точному списку git ls-files, без рекурсивной очистки. После выпуска --remote сверяет все184ресурса.
• Production-преленды остаются замороженными по preland#4. Push main ничего не публикует; staging обновляет только zoomstage.online из точного event SHA.

Доменный бренд и минимальный подвал (21.10.2026, preland#12)

Новое поручение владельца заменяет часть требований #11: в подвале остаются логотип и копирайт, без реквизитов и платёжных значков. Копирайт использует текущий HTTP_HOST без порта/trailing-dot, отдельно от config.host API; непроверенные Host и X-Forwarded-Host не выводятся.

Логотипы — готовые SVG-контуры, не текст на лету. Для zoomstage.online утверждено имя ZoomStage, слитно без зоны, обе темы. Источники лежат в brands/zoomstage.online/light.svg и dark.svg; release/brands.json содержит явную цель, имя и SHA. В docs/logo.svg и logo-alt.svg хранятся правильные canonical stage-копии для полного переноса. Их размеры182×47 совпадают с viewBox, чтобы загрузка SVG не меняла геометрию.

Обычный bin/release-assets.php --files исключает оба logo-alias из записи; runtime cache-version рассчитывается по реальному файлу хоста. Отдельный шаг release-brand.php --status разрешает только заранее согласованную миграцию #12:0 — оба SVG уже правильные, записи нет;10 — каждый файл имеет свой известный старый или новый SHA, можно закончить миграцию (включая частичный put);1 — неизвестный домен/хеш, остановка без подмены. --files выдаёт ровно утверждённые source→target. Иные логотипы не перезаписывать общим выкатом. Новые production-домены требуют отдельного добавления готовых пар и явного первоначального размещения; текущий stage-процесс их не активирует.

primary guard теперь сверяет PDF/favicon, а не заставляет возвращать Zoomzilla и реквизиты на преленд. Реквизиты не отображаются и больше автоматически не синхронизируются; хостовый config и его существующие значения не меняются этим поручением. Устаревшие requisites.html и patch-скрипт удалены из поставки. Статический manifest183, отдельный каталог брендов проверяется по собственным SHA. История #11 сохранена; её прежние инструкции о видимом бренде/реквизитах заменены этим датированным решением.

Перед выпуском: девять tests/check-*.php и lint, --check/--primary/--stage-sets, оба бренда шапки/подвала на desktop/mobile, перенос Host, отсутствие карт/реквизитов, холодная/медленная загрузка, реальные локальные Preland→Tour→Join/error/retry и геометрия. Production-преленды по #4 не включать; выпускать только staging→zoomstage.online. API продуктовый код не меняется.

Runtime indpic и отдельная админка (25.10.2026, preland#22)

Это решение явно заменяет требование #11 о предварительном импорте изменённых наборов /N/ в Git. Кодовая доставка сохраняет runtime config.json и /N/; обновление контента админкой не требует commit/push. Исторические записи /N/ в release/assets.json остаются снимком, не источником истины runtime.

php bin/release-assets.php --check сохраняет строгую проверку состава и SHA поставляемой статики, включая запрет старого бренда. --stage-sets URL и --remote URL читают фактический config и проверяют default, номера/веса indpic, затем декодируют все 90 обязательных изображений каждого используемого набора, проверяют формат и размеры по контракту API IndpicSetStorage (591a67cc8302). Проверяются также ссылки с нулевым весом: их разрешает явный UTM и legacy random. Отсутствующий indpic/default использует штатный fallback /1/; явно неверный номер/default блокируется. Конфиг перечитывается после проверки для обнаружения его изменения. Одиночный HTTP200 не считается подтверждением валидного набора.

HTTP не предоставляет inventory каталога: лишние файлы удалённого набора этим режимом не исключаются. Для строгой проверки ровно 90 файлов без симлинков, вложенных каталогов и лишних элементов выполнить на фактическом webroot php bin/check-runtime-sets.php /path/to/webroot либо проверку через транспорт админки. Локальная проверка и HTTP требуют PHP Imagick с AVIF/WebP/JPEG.

releaseFiles() — положительный список публичных кодовых/статических ресурсов. admin/, его состояние/ключи/резервы, bin/, тесты и планы не публикуются обычной доставкой прелендинга. Админка имеет отдельный образ и процедуру выпуска. Проверки перед выпуском: все tests/check-*.php, manifest --check, --primary, --stage-sets; после — --remote и проверка бренда. Не ослаблять guard ради выпуска.