@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/rules/testing.md

@@ -2,68 +2,99 @@
 name: testing
 kind: rule
 law: verifiability
-description: Правило под закон «Проверяемость». Брать при правке любого файла спеки и всего, что лежит в сквозных прогонах. Идентификатор сценария в заголовке теста, отметка непокрытого, вынос решения в чистую функцию, выключатели разрушающих спек. Готовый код — в паттернах testing-unit и testing-e2e. Чем это названо здесь — в implementation.md рядом.
+description: Правило под «Закон о проверяемости». Брать при правке любого *.spec.ts и всего, что лежит в apps/site-e2e и apps/admin-e2e. Называет Vitest и Playwright, идентификатор сценария в заголовке, вынос решения в чистую функцию и то, что закрывается сквозной спекой. Готовый код — в паттернах testing-unit и testing-e2e.
 ---
 
-# Проверяемость — каким приёмом
+# Проверяемость — как это устроено здесь
 
-Правило под закон `{{lawsDir}}/verifiability.md`. Закон говорит, что считается подтверждением;
-здесь — каким приёмом это делается. Чем это названо в этом дереве, каким прогонщиком гоняется и
-где лежит — `implementation.md` рядом. Проверка работающего приложения глазами и замером —
-правило `browser-verification` под тем же законом.
+Правило под закон `docs/constitution/verifiability.md`. Закон говорит, что считается
+подтверждением; здесь — чем это названо в этом дереве, где лежит и что из закона у нас не
+применяется. Проверка работающего приложения глазами и замером — правило
+`browser-verification` под тем же законом.
 
-## Когда берётся
+## Как это называется здесь
 
-Правка файла спеки, заведение теста, разбор упавшего прогона, закрытие сценария из спеки
-домена.
+| В законе                   | Здесь                                                                            |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| сценарий                   | `SC-<ПРЕФИКС>-<НОМЕР>` в `docs/specs/<домен>/scenarios.md`                       |
+| тест                       | `it(...)` в `*.spec.ts` рядом с исходником — Vitest; сквозная спека — Playwright |
+| сводка покрытия            | вывод `npm run check:specs`: покрыто, частично, без тестов                       |
+| отметка непокрытого        | строка `Не покрыто: <причина>` внутри блока сценария                             |
+| отметка неполного покрытия | строка `Покрытие: частичное — <чего не хватает>`                                 |
 
-## Что здесь действует
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
 
 - **Идентификатор сценария стоит в начале заголовка теста, через тире.** Один сценарий
-  проверяется несколькими тестами, один тест закрывает несколько сценариев; связь читается из
-  заголовка, а не из памяти писавшего.
-- **Сценарий без теста несёт отметку с причиной.** Пустая отметка не принимается, а отметка при
-  существующем тесте — отказ: она означает, что долг закрыли, а отметку не сняли.
-- **Тест, идущий не тем путём, что пользователь, помечается частичным покрытием.** В сводку он
-  попадает долгом, а не покрытием.
+  проверяется несколькими тестами, один тест закрывает несколько сценариев.
+- **Сценарий без теста несёт отметку с причиной.** Пустая отметка не принимается, а отметка
+  при существующем тесте — отказ: она означает, что долг закрыли, а отметку не сняли.
+- **Тест, идущий не тем путём, что пользователь, помечается частичным покрытием.** В сводку
+  он попадает долгом, а не покрытием.
+- **Сценарий, чьё «Тогда» называет человека и то, что он видит, закрывается сквозным тестом.**
+  Юнит на тот же расчёт остаётся долгом: между верным решением и тем, что человек его видит,
+  лежит всё, чего юнит не касался.
+- **Сквозной тест, погашенный переменной окружения, покрытием не считается.** Выключатель по
+  состоянию стенда — пропуск случая, выключатель по переменной — невыполненный тест.
 - **Упоминание в тесте сценария, которого в спеках нет, роняет проверку.** Так ловится
   переименованный или выкинутый сценарий: тесты при этом остаются зелёными.
 - **Решение выносится в чистую функцию и проверяется вызовом.** Компонент и сервис остаются
   тонкой обёрткой и отдельно не проверяются, пока своего ветвления у них нет.
-- **Обработчик серверной стороны проверяется вызовом своего метода с рукописным двойником
-  хранилища.** Контейнер и маршрутизатор поднимать не надо: спека проверяет решение, а не
-  раскладку полей.
-- **Спека, необратимо меняющая данные стенда, выключена по умолчанию.** Адрес стенда уводится
-  одной переменной окружения, и без выключателя такая спека правила бы данные чужого стенда.
-- **Спеки, которым нужен прокси перед приложением, просыпаются вместе с адресом стенда.** Голый
-  сервер отдачи страниц их не проходит: перенаправления живут в конфиге прокси, а не в
-  приложении.
-- **Правило линтера, которое запрещает принятый здесь приём, выключают в конфиге, а не обходят
-  в каждом тесте.** Точечное отключение в файле остаётся для того, что запрещено по делу; рядом
-  со строкой отключения пишут причину.
+- **Процедура Connect проверяется вызовом своего метода с рукописным двойником базы.**
+  Контейнер и роутер поднимать не надо: спека проверяет решение, а не раскладку полей.
+- **Спека, необратимо меняющая данные стенда, выключена по умолчанию.** `BASE_URL` уводит
+  прогон одной переменной, и без выключателя такая спека правила бы данные чужого стенда.
+- **Спеки, которым нужен nginx перед приложением, просыпаются вместе с `BASE_URL`.** Голый
+  сервер отдачи страниц их не проходит: перенаправления живут в конфиге прокси.
+- **Правило линтера, которое запрещает принятый здесь приём, выключают в конфиге, а не
+  обходят в каждом тесте.** Выключатель теста — приём этого дерева, а
+  `playwright/no-skipped-test` запретил бы его сразу в шестидесяти пяти местах. Рядом со
+  строкой отключения пишут причину, а точечный `eslint-disable` остаётся для того, что
+  запрещено по делу.
+
+## Чего из закона здесь нет
+
+Полнота теста не проверяется: сверка судит путь — сквозной он или юнит, — но не то, сколько
+из обещанного тест на этом пути закрыл. Признак пути читается из слов «Тогда» и нарочно
+молчалив: сценарий, чьё обещание человека не называет, под него не подпадает вовсе, и
+отметку неполноты там по-прежнему ставит рука. Договорённостей о подмене модулей тоже нет:
+`vi.mock` в дереве не встречается ни разу, и двойник пишется руками.
 
 ## Паттерны
 
-- `testing-unit` — тест на чистую функцию, на обработчик серверной стороны и разовый
-  тест-доказательство, который не коммитится.
-- `testing-e2e` — прогон сквозных тестов, стенд под настоящим прокси, выключатели.
+- `testing-unit` — тест на чистую функцию, на процедуру Connect и разовый тест-доказательство,
+  который не коммитится.
+- `testing-e2e` — прогон сквозных тестов, стенд под настоящим nginx, выключатели.
 
 ## Ловушки
 
-- **Зелёный прогон тестов не значит, что хоть один файл исполнялся.** Либа без своего конфига
-  прогонщика не запускает ничего. Либа с конфигом, но без единого файла спеки, проходит зелёной
-  из-за настройки «успех при отсутствии тестов», и на глаз эти два случая неотличимы: в обоих
-  прогон успешен. Перед правкой в незнакомой либе проверяется, есть ли в ней хоть один файл
-  спеки; если нет — первый заводится этой же правкой, а не откладывается: откладывать здесь не
-  с чего, долг уже накоплен.
-- **«Executable doesn't exist» — состояние машины, а не дефект правки.** Обычно установлен один
-  движок браузера, остальные падают всегда. Та же ошибка приходит после смены версии
-  прогонщика сквозных тестов: браузер ставится под конкретную версию, и после подъёма его надо
-  поставить заново. Выглядит это как регрессия обновления, а ею не является.
-- **Первому прогону сразу после установки браузера верить нельзя.** Падения, не повторяющиеся
-  ни при отдельном прогоне тех же тестов, ни при втором полном, — свойство первого прогона.
-  Такой прогон повторяют, а выводы делают по второму.
-- **Сквозные тесты без учётных данных в окружении пропускаются молча.** В отчёте они значатся
-  пропущенными, и прогон выглядит успешным.
-- **Поднятый сервер разработки проверкой не является.** Это шаг правила `browser-verification`,
-  а не тест.
+- **Зелёный `nx test <проект>` не значит, что хоть один файл исполнялся.** Либа без своего
+  `vitest.config.mts` не запускает ничего — так тесты домена броней не запускались ни разу.
+  Либа с конфигом, но без единого `*.spec.ts`, проходит зелёной из-за `passWithNoTests: true`,
+  который стоит во всех 203 конфигах дерева, и на глаз эти два случая неотличимы: в обоих
+  прогон успешен. Без единого теста живут 131 либа из 203 — почти две трети. Перед правкой в
+  незнакомой либе проверяется, есть ли в ней хоть один `*.spec.ts`; если нет — первый
+  заводится этой же правкой, а не откладывается: откладывать здесь не с чего, долг уже
+  накоплен. Пересчёт: `for d in $(find libs -name vitest.config.mts -exec dirname {} \;); do
+[ -z "$(find "$d" -name '*.spec.ts')" ] && echo "$d"; done | wc -l`.
+- **«Executable doesn't exist» — состояние машины, а не дефект правки.** Установлен только
+  chromium, `firefox` и `webkit` падают всегда: гонять `--project=chromium`, узкий экран —
+  `--project=mobile-chrome`. Та же ошибка приходит после смены версии Playwright: браузер
+  ставится под конкретную версию, и после подъёма нужен повторный
+  `npx playwright install chromium`. Девять тестов так и упали, и это выглядело регрессией
+  обновления.
+- **Первому прогону сразу после установки браузера верить нельзя.** Два падения `admin-e2e`
+  не повторились ни при отдельном прогоне тех же тестов, ни при втором полном. Такой прогон
+  повторяют, а выводы делают по второму.
+- Сквозные тесты админки без `E2E_ADMIN_EMAIL` и `E2E_ADMIN_PASSWORD` пропускаются молча — в
+  отчёте они значатся `skipped`, и прогон выглядит успешным.
+- **Справочник флоу вторых сценариев не заводит.** В `docs/E2E_<ДОМЕН>_FLOWS.md` кладут то,
+  чего в спеке домена нет и быть не должно: `qa-dataid` элементов, состояния разметки, ловушки
+  стенда. Обещанное поведение остаётся сценарием в `scenarios.md`: если списать его во второе
+  место, копии разойдутся молча — `npm run check:specs` этого не увидит.
+- `npx nx serve` проверкой не является: это шаг из правила `browser-verification`, а не тест.

package/assets/rules/translations.md

@@ -2,51 +2,68 @@
 name: translations
 kind: rule
 law: locales
-description: Правило под закон «Локали и переводы». Брать при заведении любого видимого текста, правке словарей, префиксов локалей в адресе и перевода содержимого записи. Текст из словаря во всех локалях, пустой перевод как пропуск, производные переводы содержимого, начальная валюта локали. Готовый код — в паттерне translations-key. Чем это названо здесь — в implementation.md рядом.
+description: Правило под «Закон о локалях и переводах». Брать при заведении любого видимого текста, правке словарей libs/common/i18n, префиксов локалей сайта и перевода контента объекта. Называет восемь локалей, Transloco, производные переводы и начальную валюту локали. Готовый код — в паттерне translations-key.
 ---
 
-# Локали и переводы — каким приёмом
+# Локали и переводы — как это устроено здесь
 
-Правило под закон `{{lawsDir}}/locales.md`. Закон говорит, что должно быть верно; здесь — каким
-приёмом это держится. Какие именно локали набраны, чем зовётся библиотека переводов и где лежат
-словари — `implementation.md` рядом.
+Правило под закон `docs/constitution/application/locales.md`. Закон говорит, что должно быть верно;
+здесь — чем это названо в этом дереве и где лежит. Разметка сайта для поиска — `seo` под
+своим законом.
 
-## Когда берётся
+## Как это называется здесь
 
-Заведение любого видимого человеку текста, правка словаря, правка маршрутов с префиксом локали,
-перевод содержимого записи.
+| В законе             | Здесь                                                                                               |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| локаль сайта         | одна из восьми: `en`, `ru`, `de`, `zh-Hans`, `zh-Hant`, `ko`, `th`, `hi`                            |
+| локаль по умолчанию  | `en` — отдаётся из корня, без префикса в адресе                                                     |
+| локаль ввода         | `source_locale` в запросе сохранения объекта; берётся из языка админки                              |
+| словарь              | JSON-словари Transloco в `libs/common/i18n/src/lib/dictionaries/<локаль>/`, разложенные по разделам |
+| перевод контента     | jsonb по локалям в базе, заполняется бэкендом                                                       |
+| подстановка в шаблон | `\| transloco` в разметке, `translateSignal` в классе                                               |
 
-## Что здесь действует
+## Где это лежит
 
-- **Локаль по умолчанию отдаётся из корня, остальные — из-под префикса пути.**
-- **Видимый человеку текст берётся из словаря и заводится во всех локалях сразу.** Ключ,
-  потерянный в одной локали, читатель видит на кнопке как есть.
-- **Пустой перевод считается пропуском, а не переводом.** Запасной словарь подставляется только
-  на отсутствующий ключ, а пустую строку отдаёт как есть.
-- **Переводы содержимого производные: владелец пишет на своём языке, остальные локали
-  заполняются при сохранении.** Вкладок локалей в формах нет — ручная правка всё равно была бы
-  перезаписана.
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Локаль по умолчанию отдаётся из корня, остальные семь — из-под префикса пути.**
+- **Видимый человеку текст берётся из словаря и заводится во всех локалях перевода.** Ключ,
+  потерянный в одной локали, гость видит на кнопке как есть.
+- **Пустой перевод считается пропуском, а не переводом.** Запасной словарь подставляется
+  только на отсутствующий ключ, а пустую строку отдаёт как есть.
+- **Переводы контента производные: владелец пишет на своём языке, остальные семь локалей
+  заполняет бэкенд при сохранении.** Табов локалей в формах админки нет — правка вручную всё
+  равно была бы перезаписана.
 - **Отказ перевода сохранение не срывает.** Текст на локали ввода записывается, прежние
   переводы остаются, и владелец видит предупреждение, а не сообщение об успехе.
 - **Локаль, для которой перевода не пришло, сохраняет прежнее значение.**
-- **Язык интерфейса выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
-  ввода при сохранении записи.
-- **У локали есть начальная валюта показа.** Дальше валюту выбирает читатель, и его выбор
+- **Язык админки выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
+  ввода при сохранении объекта.
+- **У локали есть начальная валюта показа.** Дальше валюту выбирает гость, и его выбор
   сильнее умолчания локали.
 
+## Чего из закона здесь нет
+
+Страница не показывает, что перевод устарел: владелец правку сохранил, провайдер отказал —
+и гость по-прежнему видит старый текст. Это `Q-L-1` в законе.
+
 ## Паттерны
 
-- `translations-key` — заведение ключа во всех локалях и подстановка в разметку.
+- `translations-key` — заведение ключа во всех локалях перевода и подстановка в разметку.
 
 ## Ловушки
 
-- **Полноту словарей держит не работающее приложение, а тест.** Он роняет прогон на
-  недостающем или пустом ключе; без него дыра видна только на экране.
-- **Наборы ключей сверяются внутри раздела**, а не по всему словарю сразу: словари разложены на
-  общий, публичную часть, письма и внутреннюю часть.
-- **Перевод содержимого идёт до записи, а не после.** Иначе страница оказывается наполовину
-  переведённой; кэш сбрасывается после записи и один раз.
-- **Без ключа доступа к переводчику сохранение проходит**, но переводы остаются прежними — и
-  единственный признак этого владелец видит предупреждением.
-- **Новый маршрут без ветки под каждую локаль существует только в локали по умолчанию.**
-  Остальные адреса отдадут отказ и поисковику, и читателю.
+- **Полноту словарей держит не рантайм, а тест.** `nx test common-i18n` роняет сборку на
+  недостающем или пустом ключе; дозаполнить недостающее — `npm run i18n:fill`.
+- **Наборы ключей сверяются внутри раздела**, а не по всему словарю сразу: словари разложены
+  на общий, сайт, письма и админку.
+- **Перевод контента идёт до транзакции сохранения:** страница объекта не должна оказаться
+  наполовину переведённой. Кэш сбрасывается после записи и один раз.
+- **Без ключа `ANTHROPIC_API_KEY` сохранение проходит,** но переводы остаются прежними, и
+  владелец видит предупреждение `propertySaveTranslationFailed`.
+- Новый маршрут сайта без ветки под каждую локаль существует только в локали по умолчанию:
+  `/de/<путь>` отдаст 404 и поисковику, и гостю.

package/assets/rules/typescript-conventions.md

@@ -2,45 +2,75 @@
 name: typescript-conventions
 kind: rule
 law: code-structure
-description: Правило под закон «Устройство кода». Брать при правке любого .ts, кроме тех, у которых есть своё правило, — род объявления в имени, модификаторы доступа, приватные поля, суффикс источника, запрет приведения в переводчике моделей. Чем это названо здесь — в implementation.md рядом.
+description: Правило под «Закон об устройстве кода». Брать при правке любого .ts, кроме компонента, сервиса, директивы, пайпа, гарда и интерцептора — строгая типизация, модификаторы доступа, приватные поля, имена файлов, префиксы, перечисления, запрет приведения в маппере, процедуры Connect на бэкенде. Готовый код процедуры — в паттерне ts-procedure.
 ---
 
-# Устройство кода — каким приёмом
+# Устройство кода — как это устроено здесь
 
-Правило под закон `{{lawsDir}}/code-structure.md`. Закон говорит, что должно быть верно про
-объявления; здесь — как это записывается. Какими правилами линтера это держится и где они
-лежат — `implementation.md` рядом.
+Правило под закон `docs/constitution/code-structure.md`. Закон говорит, что должно быть верно
+про объявления; здесь — как это записано в этом дереве.
 
-## Когда берётся
+## Как это называется здесь
 
-Правка любого файла с кодом, у которого нет своего правила: функции, типа, перечисления,
-переводчика моделей, обработчика серверной стороны.
+| В законе                    | Здесь                                                     |
+| --------------------------- | --------------------------------------------------------- |
+| признак рода в имени        | префикс: `I` у интерфейса, `E` у перечисления, `T` у типа |
+| источник, за которым следят | суффикс `$` у наблюдаемого и `Source` у субъекта          |
+| приватное поле              | `#field`, а не `private field`                            |
+| процедура бэкенда           | класс с меткой `@ConnectProcedure()`, один на процедуру   |
 
-## Что здесь действует
+## Где это лежит
 
-- **Род объявления виден по префиксу имени, и это держат правила линтера.** У интерфейса, у
-  типа и у перечисления свои; проверяются все файлы с кодом, а не выборочно.
-- **Источник, за которым следят, назван суффиксом.** Пишущий источник и наблюдаемое, поднятое
-  из него, различаются в месте использования, а не переходом к объявлению.
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Род объявления виден по префиксу имени, и это держат три правила линтера.** У интерфейса,
+  у типа и у перечисления свои; все три подняты для всех `.ts`.
+- **Источник, за которым следят, назван суффиксом.** Субъект и наблюдаемое, поднятое из него,
+  различаются в месте использования, а не переходом к объявлению.
+- **Суффикс имени файла находит в нём обещанное объявление.** Список суффиксов закрыт: слово,
+  которого в нём нет, суффиксом не считается, и такой файл правило не судит.
 - **Тип берётся из того пакета, где объявлен.** Своя копия чужого типа расходится с оригиналом
   молча, а компилируется из них только одна.
-- **Отметка об устаревании ставится вместе с обходом потребителей.** Пометка на типе красит
-  каждое место, где его ещё зовут: один `@deprecated` на файл даёт замечания во всех чужих
-  доменах разом, и правка перестаёт быть локальной.
-- **Приведение значения к типу в переводчике моделей не пишется.** Оно принимает любое значение
-  и компилируется — то есть снимает ровно ту проверку, ради которой переводчик и заведён.
+- **Двухступенчатое приведение `as unknown as` запрещено правилом линтера.** Вместо него —
+  честный тип, сужение проверкой или чтение поля формой (`Reflect.get`); место, где иначе
+  нельзя, помечается точечным отключением с причиной в той же строке.
+- **Отметка об устаревании ставится вместе с обходом потребителей.** Все правила
+  `eslint-plugin-sonarjs` подняты до отказа разом, и пометка на типе красит каждое место, где
+  его ещё зовут: один `@deprecated` на файл дал семнадцать замечаний в чужих доменах.
+
+## Чего из закона здесь нет
+
+Одноступенчатое приведение остаётся непроверенным — это `Q-CS-4` в законе: из семидесяти
+шести приведений восемь обязательны, и общий запрет отбивал бы их.
+
+Тесты из-под запрета выведены целиком: рукописный двойник базы — принятый здесь приём, и
+запрет пришлось бы обходить в каждом из тридцати пяти.
+
+Правило имён файлов судит обещание, а не его отсутствие: `menu.items.ts` и `sign-in.ts` под
+него не подпадают вовсе — это `Q-CS-3` в законе. Из двух принятых здесь форм перевода
+сущности — класс на фронте и чистые функции на бэкенде — правило принимает обе: оно судит
+имя, а не устройство, и что форм две, остаётся вопросом `Q-S-1` в законе об общем коде.
+
+На `libs/api/**` и `apps/api/**` правило действует целиком, а вот сигнальный API и `inject`
+туда не относятся: там NestJS с конструкторным DI.
 
 ## Паттерны
 
-- `ts-procedure` — завести обработчик серверной стороны: класс, метка, право, регистрация.
+- `ts-procedure` — завести процедуру Connect на бэкенде: класс, метка, право, регистрация.
 
 ## Ловушки
 
-- **Неиспользуемый параметр убирается, а не переименовывается.** Подчёркивание перед именем
-  прячет замечание, но параметр остаётся в сигнатуре и продолжает обещать значение.
-- **Агрегат хранилища своим сгенерированным типом не аннотируется.** Сгенерированный тип шире,
-  чем результат выборки, и аннотация врёт — причём в сторону, которую компилятор не оспорит.
-- **Своё правило линтера включается вместе с переводом всех, кого оно ловит.** Включённое
-  поверх накопленного даёт красный прогон на файлах, которых правка не касалась.
-- **Приватное поле с решёткой видно только внутри класса.** Там, где к полю обращается шаблон
-  или обёртка каркаса, оно объявляется защищённым, а не приватным.
+- Приведение через `as Type` в маппере запрещено, но не стережётся ничем: оно принимает любое
+  значение и компилируется. Вместо него — `this.typeCast`.
+- Неиспользуемый параметр убирается, а не переименовывается: подчёркивание перед именем прячет
+  замечание, но параметр остаётся в сигнатуре.
+- Агрегат Prisma своим типом не аннотируется: сгенерированный тип у него шире, чем результат
+  выборки, и аннотация врёт.
+- Своё правило линтера включается вместе с переводом всех, кого оно ловит: включённое поверх
+  накопленного даёт красный прогон на файлах, которых правка не касалась.
+- `#field` виден только внутри класса и не принимается `viewChild` — там поле объявляется
+  `protected`.

package/assets/skills/agent-kit.md

@@ -0,0 +1,85 @@
+---
+name: agent-kit
+description: Переносимый слой правил агента — законы, правила, хуки и проверки, которые везёт пакет, а дерево настраивает надстройками. Брать, когда правится файл с шапкой rt-kit, обновляется пакет, отказывает `sync --check`, или своё поведение надо дописать поверх пакетного. Как заводится сам скил — write-a-skill; устройство слоёв текста — spec-driven.
+---
+
+# Переносимый слой правил
+
+Законы, правила, паттерны, хуки, проверки и роли везёт пакет; дерево берёт их раскладкой и
+настраивает надстройками. Разложенный файл несёт шапку и правке не подлежит — правится либо
+пакет, либо надстройка.
+
+## Когда брать
+
+- В файле, который собираешься править, стоит шапка
+  `rt-kit v<версия> · <ресурс> · <сумма> · правится надстройкой, не здесь`.
+- Обновился пакет, или `sync --check` отказал в гейте пуша.
+- Своё поведение надо дописать поверх пакетного: гард, карта гейта, набор проверок.
+- Пакет ставится в дерево, где хуки и проверки уже свои.
+
+## Где что настраивается
+
+| Что меняешь                                    | Куда правка                                        |
+| ---------------------------------------------- | -------------------------------------------------- |
+| какое правило гейт требует под какой файл      | `.claude/rt-kit/gate-map.sh` — своя `skill_for`    |
+| порты, адреса, линтеры, форма ветки, инвентарь | `.claude/rt-kit/project.sh` — свои `rt_*`          |
+| пути и идентификаторы, которыми живут проверки | `.claude/rt-kit/checks.json`                       |
+| раздел разложенного текста                     | `.claude/rt-kit/overrides/<идентификатор ресурса>` |
+| что брать, а от чего отказаться                | `.claude/rt-kit.json`, ключи `only` и `skip`       |
+| сам механизм — гард, проверка, текст правила   | ресурс в пакете                                    |
+
+Надстройка объявляет функцию заново и вправе позвать умолчание тем же именем с суффиксом
+`_default`. Слияние текста идёт по разделам `## `: совпавший заголовок замещает, новый
+дописывается, пустой снимает раздел пакета.
+
+## Порядок
+
+Правка ресурса доезжает до дерева только через сборку пакета: строка запуска читает собранное,
+а не исходники ресурсов. Порядок один и тот же всегда — правка, сборка, `sync`. Отказ хотя бы
+по одному файлу не пишет ничего: половина разложенного хуже целого.
+
+## Команды
+
+```bash
+npx agent-kit doctor        # что разложено, что отстало, что лежит от отказанного
+npx agent-kit sync          # разложить
+npx agent-kit sync --check  # ничего не писать, отказать при расхождении
+```
+
+## Установка туда, где уже всё своё
+
+1. `init`, затем `skip` на всё, что дерево держит само. Пустая раскладка — законное начало.
+2. Снимок того, что говорят проверки дерева, до единой правки. Он и есть мерило.
+3. Ресурс за ресурсом: пакетную редакцию довести до здешней, предметность вынести в
+   надстройку, снять отказ, разложить, прогнать сценарии и сверить снимок.
+4. Разложенное поверх своего пакет не пишет: файл без шапки для него чужой. Снять его —
+   решение владельца, и до этого раскладка отказывает поимённо.
+
+## Ловушки
+
+- **Линтер по следам правки судит файл целиком, а не внесённую правку.** Импорт, добавленный
+  отдельным шагом, отбивается как неиспользуемый ещё до того, как появится строка, которая его
+  зовёт, и работа встаёт на половине. Правка делается одним вызовом либо в порядке «сначала
+  использование, потом импорт».
+- **Прогонять сценарии гардов можно, ничего не раскладывая.** Обвязка набора принимает каталог
+  гардов переменной, и пакетную редакцию гоняют по сценариям дерева до установки. Заход,
+  потраченный на диагноз по последствиям, стоил ровно этой строки.
+- **Отбитая правка не всегда про текст гарда.** Гард зовут по пути, и файл без права на
+  запуск отвечает отказом доступа — ненулевым кодом, который читается как «правка отбита».
+  Набор при этом отбивает подряд всё, включая сборку и тесты, и причины не называет.
+- **Правка shell-скрипта заменой по шаблону сверяется `bash -n` сразу.** Замена границ
+  конструкции не видит: `case` теряет свою `esac`, файл остаётся синтаксически неверным, а
+  гард с ошибкой синтаксиса отвечает ненулевым кодом — то есть «правка отбита». Два раза за
+  заход, и оба раза это выглядело дефектом самого гарда.
+- **Разложенный файл узнаётся по шапке, а не по каталогу.** Раскладка ложится в те же
+  `tools/`, `.claude/hooks/` и `.claude/skills/`, где лежит своё, поэтому карта гейта,
+  написанная по путям, требует под него доменное правило — а оно уводит править файл на месте.
+  Правка на месте теряется на следующей раскладке, и до тех пор выглядит применённой. Ветка по
+  шапке ставится в карте первой и решает раньше путей.
+- **Настройки проверок сливаются на один уровень.** Верхние ключи `checks.json` ложатся поверх
+  умолчаний по одному, а вложенный объект замещается целиком: назвав один ключ борды, дерево
+  теряет остальные — и увидит это отказом «нет токена бота», то есть как неполадку машины.
+  Вложенный раздел заполняется целиком либо не заводится вовсе.
+- **Утверждение правила переезжает вместе с кодом.** Вынесенное в надстройку перестаёт
+  находиться по прежнему символу, и привязка в спутнике правила врёт молча — сверка спеков
+  ловит это, но только если её позвать.

package/assets/skills/write-a-skill.md

@@ -0,0 +1,108 @@
+---
+name: write-a-skill
+description: Заведение нового скила — того, у которого нет закона над собой: витрина, генератор, чужой сервис, приём работы этого дерева. Брать, когда просят завести, написать или переписать скил. Форма правила и паттерна сюда не входит — это паттерн spec-driven-rule.
+---
+
+# Как заводится скил
+
+Скил — это то, что агент загружает перед работой и читает целиком. Отсюда всё остальное: он
+короткий, он объявляет, когда его брать, и он не пересказывает то, что уже написано в соседнем.
+
+## Когда брать
+
+- Заводится скил, у которого нет закона над собой: витрина, генератор, работа с чужим сервисом,
+  приём, принятый в этом дереве.
+- Скил разросся, и его пора делить.
+- Скил есть, но его никто не загружает — надо чинить объявление.
+
+**Правило и паттерн сюда не идут.** Правило стоит под законом, паттерн — при правиле, и форму
+обоих держит паттерн `spec-driven-rule`. Скил без закона — третий случай, и только он здесь.
+
+## Порядок
+
+1. **Спроси, чего не хватает.** Какую работу скил закрывает, на чём спотыкались без него, нужны
+   ли готовые команды или хватает порядка действий. Скил, написанный без этого, пересказывает
+   документацию инструмента — а её агент и так знает.
+2. **Напиши черновик.** Один файл. Дополнительные — только когда первый перестаёт читаться
+   целиком.
+3. **Покажи владельцу.** Скил действует на все будущие сессии, и заводить его молча нельзя.
+
+## Что в файле
+
+```
+<имя-скила>/
+├── SKILL.md          # обязателен, и обычно единственный
+├── <ЧТО-ТО>.md       # отдельный файл — когда SKILL.md перестал читаться целиком
+└── scripts/          # готовые скрипты, если операция детерминированная
+```
+
+Вступление между `---` — `name` и `description`, дальше заголовок и разделы. Первым разделом —
+«Когда брать»: агент решает по нему, а не по названию.
+
+## Объявление решает всё
+
+`description` — **единственное, что агент видит**, когда решает, грузить скил или нет. Он стоит
+в системном приглашении рядом с описаниями всех остальных, и выбор идёт по ним.
+
+Оно отвечает на два вопроса: что скил даёт и когда его брать. Пиши третьим лицом, до 1024
+знаков: первая фраза — что делает, вторая — «Брать, когда…», третья — чего в нём нет и где это
+искать.
+
+```
+✓ Заведение нового скила — того, у которого нет закона над собой. Брать, когда просят
+  завести, написать или переписать скил. Форма правила и паттерна сюда не входит — это
+  паттерн spec-driven-rule.
+
+✗ Помогает со скилами.
+```
+
+Второе объявление не даёт агенту ни одного способа отличить этот скил от соседнего — и он не
+загрузит ни один.
+
+Строка «чего здесь нет» не украшение: скилов в дереве десятки, и половина ошибок выбора — это
+взятый соседний. Назови его по имени.
+
+## Готовые команды вместо описания
+
+Скрипт кладётся рядом со скилом, когда операция детерминированная — проверка, приведение к
+форме, разбор вывода. Такое дешевле позвать, чем породить заново, и ошибку в нём видно один раз,
+а не в каждом порождении.
+
+Порядок действий, зависящий от того, что нашлось, скриптом не становится: он остаётся текстом.
+
+## Когда делить
+
+Делить, когда:
+
+- файл перестал читаться целиком — по опыту это около сотни строк;
+- в нём два разных предмета, и второй нужен раз в месяц;
+- готовый код занял больше места, чем объяснение, зачем он.
+
+Не делить ради красоты: два файла вместо одного стоят одного лишнего перехода при каждом
+чтении, а ссылка глубже одного уровня не читается вовсе.
+
+## Чем скил вредит
+
+- **Пересказ документации инструмента.** Агент читает скил при каждой работе; строка, которую он
+  знает и без того, вытесняет ту, которой не знает.
+- **Дублирование соседа.** Два скила об одном начинают противоречить друг другу, и первым это
+  замечает тот, кто выполнил оба.
+- **То, что устареет вместе с кодом.** Скил, называющий версию, число или имя файла, которое
+  правится чаще раза в квартал, врёт молча.
+- **Длина.** Скил в три экрана перестают читать целиком, а читают до первого знакомого раздела.
+
+## Перед тем как отдать
+
+- [ ] в объявлении есть «Брать, когда…» и назван сосед, которого брать не надо;
+- [ ] первый раздел — «Когда брать»;
+- [ ] файл читается целиком за один заход;
+- [ ] ни одной строки, которая повторяет соседний скил;
+- [ ] ничего, что устареет само собой: версий, чисел, сроков;
+- [ ] есть хотя бы один готовый пример, а не только объяснение;
+- [ ] ссылки уходят на один уровень, не глубже.
+
+## Чтобы скил загружали
+
+Написанного мало: скил, который никто не открывает, не действует. Новый скил либо называется в
+карте гейта этого дерева, либо его зовёт по имени другой скил или роль. Скил, не названный
+нигде, останется декорацией.