chatballs/AGENTS.md

Если в окружении не доступен инструмент, например - Python, PHP, попробуй docker, если в проекте есть его файлы.

Тесты: гонять только те, что относятся к изменённому в текущем шаге. Полный
прогон — только по моему явному указанию, никогда по своей инициативе. Полный
набор идёт ~20 минут, и гонять его после каждой правки запрещено.

Без моего явного указания не меняй ничего!
Если я задал вопросы, это не значит что ты можешь менять файлы!
Любые правки только после моего явного указания, например - "делай".
Соблюдай инструкцию по коммитам.
Используй glab, gh если доступны.

Учетные данные / доступы:
- Без явного указания владельца не менять, не сбрасывать, не bootstrap-ить и не пересоздавать никакие учетные данные, пароли, TOTP, recovery-коды, сессии и права доступа.
- Если для проверки нужен вход в приложение, использовать только уже существующие учетные данные, предоставленные владельцем, и не выполнять команды, которые могут изменить пароль или состояние аккаунта.
- Любые команды управления аккаунтами, включая `bootstrap_owner`, password reset/change, seed пользователей и изменение ролей, требуют отдельного явного подтверждения владельца перед запуском.

Production deployment / миграция:
- Не принимать самостоятельно решения о способе переноса production-данных, bind mounts, путях хранения, переключении каталогов или удалении старого deployment.
- Перед любым изменяющим действием в production сначала представить владельцу точный план миграции и получить его явное согласование. Разрешение на диагностику или общая просьба «исправить» не являются разрешением самостоятельно выбирать архитектуру миграции.

UI / дизайн:
- Никакой отсебятины в UI: не добавлять экраны, блоки, карточки, иконки, тексты, анимации, цвета, layout-решения и состояния, которых нет в утверждённом дизайн-макете (`design/baseline/<фича>/*.dc.html`). Макет — источник истины, README рядом с ним лишь пересказ.
- Если UI-этап еще не наступил, UI не считается реализованным и не должен маскироваться под готовый продуктовый интерфейс.
- Для построения UI использовать существующие компоненты и их стили, если они уже реализованы; если подходящего компонента нет, создавать переиспользуемый компонент в рамках существующей системы.
- Не упрощать UI, анимации, иконки, состояния или поведение по своему усмотрению. Любое отклонение от baseline требует явного согласования до правок.
- Технические временные заглушки UI не считать готовой реализацией и не использовать как основу продуктового UI без отдельного явного разрешения.

Один стандарт на один элемент:
- Ссылки во всём приложении выглядят одинаково. Единая база — класс `.link` из `shared/links.css`, одинаковый и для `<a>`, и для `<button>`. Роль задаётся модификатором: `.is-strong` (имя сущности), `.is-neutral` (тёмное имя, синее при наведении), `.is-muted` (второстепенная, «Назад», «Отмена»), `.is-mono` (идентификаторы), `.has-icon` (с иконкой). Заводить в фиче свой `*-name-link`, `*-meta-link`, `*-link-button` запрещено.
- Действие, а не переход, оформляется `<button className="link">`, а не `<a href="#">` с `preventDefault`.
- Выпадающие меню — только antd `Dropdown` с `overlayClassName="app-dropdown"` и триггером `.row-menu-button`. Своих меню на `position: absolute/fixed`, ручном расчёте координат и подложек-скримов не делать: портал закрывается по клику вне и по Esc сам и не обрезается `overflow`.
- Перед тем как написать свой элемент, искать существующий в `shared/` и в соседних фичах. Второй стандарт того же элемента — это дефект, а не свобода реализации.

Никаких служебных записок в продукте:
- В продуктовом UI не должно быть служебной лексики. Запрещены на экране: коды спек и решений (SPEC-HUB-*, ADR-HUB-*, DG-*), номера правил (P1-P5 и любые другие), слова «инвариант», «констрейнт», «миграция», «scope» в техническом смысле, имена таблиц, полей и enum-значений БД и API (`allowCheckoutActions`, `Conversation.channel`, `PROTECT`, `OK`/`ERROR` как есть), ссылки на внутренние документы и любые пометки для разработчика.
- Пользователю показывается следствие и способ исправить, а не внутреннее правило. «Коммерческие действия недоступны непродуктовому каналу. Назначьте продукт» — да. «Запрещено инвариантом P1» — нет.
- Технические коды остаются в коде, комментариях, логах и API-ответах, но не в текстах интерфейса.
- Это относится и к baseline-макетам: служебный текст, попавший в макет, не является основанием выводить его на экран. Макет реализуется, дополняется по указанию владельца, служебная лексика в реализацию не переносится.
- Правило действует на прод в первую очередь: ни одна служебная пометка не должна доезжать до пользователя.

Engineering rules / обязательные практики:
- Соблюдать DRY, KISS, SRP, separation of concerns и NO GOD FILES.
- Не реализовывать полноценную страницу, feature или крупный workflow одним большим компонентом/файлом.
- Если компонент превышает примерно 200 строк или смешивает layout, state, data/model и subviews, разделить его до завершения задачи.
- Если новый или измененный файл превышает примерно 300 строк из-за текущей работы, остановиться и вынести части в меньшие модули до финального ответа или коммита.
- Page-компоненты должны быть преимущественно composition-only: subviews выносить в соседние компоненты, демо/static data в model/data файл, повторяемый UI в shared/local reusable components.
- Не инлайнить сложный UI повторно. Выносить компонент, если структура повторяется или секция имеет отдельную ответственность.
- Если реализация по задаче конфликтует с этими правилами, остановиться и явно сообщить blocker вместо поставки плохой структуры.

Язык интерфейса:
- Текста, который видит человек, в коде не бывает. Строка живёт в словаре и подставляется через `t(...)`: во фронтенде это `src/i18n` приложения (`packages/ui` — свой словарь), на бэкенде `chatballs/i18n`. Русский каталог — источник ключей, английский обязан его повторить: пропущенный перевод во фронтенде ловит `tsc`, на бэкенде — тест каталога.
- Ключ пишется от смысла, а не от фразы: `settings.storage_bucket_name`, а не пересказ текста. Строку переформулируют чаще, чем переименовывают.
- Число не склоняют вручную: формы задаёт словарь, форму выбирает `tn(...)`. Дату, размер файла и разряды числа форматирует `fmt` — прибитые `"ru-RU"` и свои списки месяцев запрещены.
- Что записано в базу, переводится по коду, а не текстом: системные события диалога, уведомления и подписи журнала аудита хранят код, а фразу собирает бэкенд на языке читателя. Писать в историю готовую русскую фразу нельзя — её потом не перевести.
- Язык запроса выбирается цепочкой: профиль сотрудника → организация → установка → браузер. Письмо получает язык адресата, а не отправителя.
- На бэкенде `t(...)` не вызывается на уровне модуля: язык там свой на каждый запрос, а константа посчиталась бы один раз при импорте.
- Текст, уходящий наружу — клиенту в мессенджер, письмо, кнопку виджета, — берёт язык не запроса, а организации: `t(..., language=customer_language(organization))`. Язык оператора, нажавшего кнопку, к речи компании с её клиентом отношения не имеет, и половина такого текста вообще рождается в воркере, где запроса нет.
- Системный промпт агента не переводится: его читает модель. Язык ответа задаёт отдельная директива по полю `AIAgent.answer_language` — по умолчанию «как у клиента».
- Демо-набор ставится на языке организации: манифесты лежат в `demo_seed/data/<язык>/`, наборы ключей в них совпадают. Бинарные вложения (аватары, голосовые) общие, текстовые документы — свои на каждый язык.

Definition of Done:
- Запускать только тесты, относящиеся к изменениям текущей итерации: изменил
  presence — гоняешь тесты присутствия, изменил тексты — гоняешь каталог i18n.
  Полный прогон всех тестов выполнять ТОЛЬКО по явному указанию владельца.
  Использовать `--reuse-db`; `--create-db` — лишняя минута на переигрывание
  миграций, она нужна только когда схема действительно поменялась.
- Измененные файлы должны быть проверены на NO GOD violations.
- Новый компонент не должен владеть несвязанными ответственностями.
- Не должно быть придуманных текстов, иконок, layout-решений или состояний вне design/docs.
- Любое отклонение от design/docs должно быть явно указано.