@rt-tools/agent-kit 0.5.2 → 0.6.0

package/assets/patterns/observability-record.md

@@ -0,0 +1,114 @@
+---
+name: observability-record
+kind: pattern
+rule: observability
+description: Паттерн правила observability. Брать, когда в коде заводится новая строка лога — готовый вызов логгера, выбор уровня, имя строки, поля объектом, отказ внешней службы и предел ожидания. Не брать для правки самого логгера и контекста запроса — это правило observability.
+---
+
+# Новая строка лога
+
+Паттерн правила `observability`. Что при этом должно быть верно — закон
+`docs/constitution/observability.md`.
+
+## Когда брать
+
+- В домене появилось место, о котором владелец должен узнать: не сработала автоматика,
+  отказала внешняя служба, упала процедура.
+- Хочется поставить `console.log` — вместо него ставится строка лога.
+
+## Логгер домена берётся один раз
+
+```ts
+const LOG_CONTEXT: string = 'PageCache';
+
+readonly #log: ScopedLogger;
+
+constructor(logger: AppLoggerService) {
+    this.#log = logger.scope(LOG_CONTEXT);
+}
+```
+
+Контекст задаётся один раз и константой модуля, а не литералом в вызове: соседние классы одного
+домена пишут под тем же источником, а отбор отказов судит именно по нему. Номер обращения,
+процедуру и того, кто в системе, логгер подставляет сам — передавать их полями не надо.
+
+## Имя строки постоянное, всё изменяемое — в поля
+
+```ts
+✓ this.#log.warn('cache.refresh.rejected', { url, attempt, status, durationMs });
+✗ this.#log.warn(`cache refresh rejected for ${url} after ${attempt} attempts`);
+```
+
+Первый аргумент — имя строки, а не предложение. По нему строки об одном и том же собираются
+вместе, и по нему же они схлопываются в одну строку ленты отказов. Подставленное в имя значение
+делает каждую строку уникальной.
+
+Имя пишется точками от общего к частному: `cache.refresh.rejected`, `mail.owner.skipped`.
+
+Поля вычищаются автоматически. Имя строки проходит вычистку только по пути в хранилище отказов
+— в выводе оно печатается как есть, — поэтому подставлять в него значения нельзя ещё и по этой
+причине.
+
+## Строке нижнего уровня нужна строка в списке отобранных
+
+Уровень отказа и всё, что выше, уезжает в хранилище отказов само. Строка уровнем ниже попадает
+туда, только если её имя стоит в списке отобранных имён. Список сравнивается по началу имени и
+правится тем же коммитом, что и место, которое эту строку пишет.
+
+Забыли дописать — строка останется только в выводе контейнера, и владелец о ней не узнает. Не
+сверяет это ничто.
+
+## Уровень выбирается по тому, сломалось ли что-то
+
+| Уровень     | Когда                                                                                                    |
+| ----------- | -------------------------------------------------------------------------------------------------------- |
+| отказ       | приложение не сделало того, что должно: упала процедура, не прошла запись в хранилище                    |
+| ниже        | не сработала автоматика: перевод, обновление кэша, опрос внешней службы. Сюда же отказ по вводу и правам |
+| сообщение   | состоявшееся действие, о котором стоит знать: вызов прошёл, письмо ушло                                  |
+| подробность | то, что нужно при разборе, а на проде не нужно                                                           |
+
+Отказ гостя пройти проверку, промах в форме и «не найдено» — это уровень ниже отказа. Проверка
+сработала, приложение работает.
+
+## Отказ внешней службы записывается разобранным
+
+```ts
+} catch (error: unknown) {
+    this.#log.error('mail.send.failed', { to: maskEmail(to), error: describeError(error) });
+}
+```
+
+Разбор причины кладёт класс, текст, код и срезанный стек одной формой — той же, что у остальных
+отказов. Подставлять ошибку в текст (`` `failed: ${String(error)}` ``) нельзя: так в лог уедет
+чужой текст целиком, вместе с адресом, ключом или почтой гостя.
+
+Почту маскируют на месте вызова, если она приходит отдельным значением: вычистка узнаёт её по
+имени поля, а имя вроде `to` на почту не похоже.
+
+## Отказ наступает только тогда, когда у обращения есть предел ожидания
+
+```ts
+/**
+ * Ожидание источника курсов. Курс справочный и обновляется раз в сутки: пять
+ * секунд ожидания и прежний курс на месте лучше, чем пять минут занятого
+ * расписания.
+ */
+const RATES_TIMEOUT_MS: number = 5_000;
+
+const response: Response = await fetch(RATES_URL, { signal: AbortSignal.timeout(RATES_TIMEOUT_MS) });
+```
+
+Без предела соединение с молчащей службой живёт до умолчания среды — минуты, — и всё это время
+`catch` не наступает: писать нечего. Число стоит рядом с клиентом со своим доводом, потому что
+цена ожидания у каждой службы своя: гость внутри запроса ждёт иначе, чем ночное расписание.
+
+## Частые промахи
+
+- **Одно и то же имя строки стоит в двух местах.** Тогда две разные ситуации читаются как одна.
+  Либо имена разные, либо место одно.
+- **`console.log` вместо строки лога.** У него нет ни уровня, ни номера обращения, и в отбор он
+  не попадает. На проде это строка, которую никто не увидит.
+- **Уровень выбран по тому, насколько неприятно.** Отказ гостя пройти проверку неприятен, но
+  приложение при этом работает.
+- **Ошибка положена в поле как есть, без разбора причины.** Объект ошибки сериализуется в
+  пустой `{}`, и в логе не останется ни текста, ни класса.

package/assets/patterns/ownership-session-procedure.md

@@ -0,0 +1,102 @@
+---
+name: ownership-session-procedure
+kind: pattern
+rule: ownership-session
+description: Паттерн правила ownership-session. Брать, когда процедуре нужна владеющая сущность захода — объявление декоратором, чтение из контекста, отбивка чужой сущности в черновике, контекст в тесте. Не брать для объявления доступа к процедуре — это паттерн permissions-procedure, и не для формы самого класса — это паттерн ts-procedure.
+---
+
+# Процедура, которой нужна сущность захода
+
+Паттерн правила `ownership-session`. Что при этом должно быть верно — закон
+`docs/constitution/application/ownership.md`.
+
+## Когда брать
+
+- Процедура работает с записями владеющей сущности и должна знать, в какой она работает.
+- Процедура читает идентификатор сущности из полей запроса — так больше не делают.
+- Пишется тест процедуры, которая сущность захода читает.
+
+## Объявление и чтение
+
+Две строки пишутся вместе: декоратор на классе и чтение из контекста в теле. Перехватчик читает
+сущность только для объявивших, поэтому чтение без декоратора отвечает внутренней ошибкой — и
+отвечает на первом вызове, а не на сборке.
+
+```ts
+@Injectable()
+@ConnectProcedure()
+@RequiresPermission('settings:view')
+@RequiresOwner()
+export class GetSettingsProcedure implements IConnectProcedure<typeof SettingsContract.method.getSettings> {
+    public async handle(
+        _request: GetSettingsRequest,
+        context: HandlerContext
+    ): Promise<MessageInitShape<typeof GetSettingsResponseSchema>> {
+        const settings: IOwnerSettings = await this.#settings.byOwner(ownerOf(context));
+        …
+    }
+}
+```
+
+Запрос при этом не читается вовсе — отсюда `_request`. Поля сущности в контракте нет: номер и
+имя помечены занятыми, а присланный ключ отбивается разбором запроса. Заводить его заново
+нельзя: сущность в запросе называет только тот, кто работает поверх всех сразу.
+
+Декоратор потребности стоит рядом с объявлением доступа, а не вместо него: объявлений доступа у
+процедуры по-прежнему ровно одно, и без него приложение не поднимется.
+
+## Идентификатор, названный в теле запроса
+
+Некоторые запросы несут сущность не отдельным полем, а внутри черновика. Расхождение с
+сущностью захода отбивается, а не выправляется молча:
+
+```ts
+const sessionOwnerId: string = ownerOf(context);
+if (draft.id && draft.id !== sessionOwnerId) {
+    throw new ConnectError('owner does not match the session owner', Code.InvalidArgument);
+}
+```
+
+Пустой идентификатор в черновике законен: он приходит пустым, когда админка сохраняет то, чего
+ещё не загружала.
+
+## Контекст в тесте
+
+Двойника перехватчика заводить не надо — в контекст кладётся готовое значение:
+
+```ts
+function context(ownerId: string): HandlerContext {
+    const values: ContextValues = createContextValues();
+    values.set(kSessionOwner, ownerId);
+
+    return { values } as unknown as HandlerContext;
+}
+```
+
+Тест на то, что присланный идентификатор не читается, пишется отдельным случаем: запрос несёт
+чужую сущность, а спросили у хранилища свою.
+
+```ts
+it('SC-OWN-54 — читает сущность захода и присланный идентификатор не смотрит', async () => {
+    const request: GetSettingsRequest = create(GetSettingsRequestSchema, { ownerId: FOREIGN_OWNER });
+
+    await procedure.handle(request, context(SESSION_OWNER));
+
+    expect(asked).toEqual([SESSION_OWNER]);
+});
+```
+
+## Частые промахи
+
+- Декоратор забыт, а чтение в теле стоит. Сборка и линт молчат, отказ приходит на первом вызове.
+  Ловится тестом процедуры, а не проверками дерева.
+- Декоратор поставлен вместо объявления доступа. Приложение не поднимется: у процедуры обязано
+  быть ровно одно объявление доступа, а потребность в сущности к ним не относится.
+- Сущность прочитана из запроса «на всякий случай, если контекст пуст». Пустой контекст здесь
+  означает забытое объявление, и подстановка прячет его до самого прода.
+- Процедура читает сущность захода у гостя. Вошедшего у гостевых процедур нет, и сущности в
+  контексте у них тоже нет: они берут её у записи, с которой пришли, — у страницы, у разговора
+  по токену, — а когда записи нет вовсе, у единственной сущности хранилища. Второй в хранилище
+  они отвечают отказом по состоянию.
+- Отказ на снятую принадлежность подан как отказ в доступе. Транспорт админки уводит на вход
+  только по коду неаутентифицированного, а на второй код человек остаётся на закрытом разделе.

package/assets/patterns/seo-verify.md

@@ -32,7 +32,7 @@ PORT={{prodSitePort}} node dist/apps/site/server/server.mjs &
 ## Что смотреть в отданном HTML
 
 ```bash
-for locale in "" ru/ de/ zh-Hans/ zh-Hant/ ko/ th/ hi/; do
+for locale in "" <префиксы локалей>; do
     printf '%-10s ' "${locale:-en}"
     curl -s -H "Host: localhost" "http://localhost:{{prodSitePort}}/${locale}<адрес страницы>" \
         | grep -c -E '<title>|name="description"|property="og:|rel="canonical"|hreflang=|application/ld\+json'

package/assets/patterns/spec-driven-rule.md

@@ -125,3 +125,8 @@ description: Паттерн правила git-workflow. Брать … Не б
   проверка перестанет её находить.
 - В `description` не сказано, когда паттерн **не** брать, — соседний паттерн того же правила
   становится неотличимым.
+- Блок готового кода принят по виду, а не сверкой с объявлением. Вызов в примере повторяет имя,
+  число и порядок параметров живой функции: двухпараметрный вызов выглядел правдоподобно ровно
+  до того, как рядом открыли четырёхпараметрное объявление. Тем же проходом сверяется форма
+  кода — пример, объявляющий поля не так, как их объявляет дерево, учит нарушать правило о
+  языке, и запрещающее правило про это не узнает.

package/assets/patterns/styling-bem-sheet.md

@@ -0,0 +1,178 @@
+---
+name: styling-bem-sheet
+kind: pattern
+rule: styling-bem
+description: Паттерн правила styling-bem. Брать при заведении или правке шторки, окна и полноэкранного просмотра поверх страницы — чем открывается, что передаётся внутрь, как приезжает снизу, чем проверяется. Не брать для панели правки записи в админке — это паттерн entity-aside.
+---
+
+# Шторка и окно поверх страницы
+
+Паттерн правила `styling-bem`. Что при этом должно быть верно — закон
+`docs/constitution/frontend-application.md`.
+
+## Когда брать
+
+- На телефоне заводится шторка: выбор языка, валюты, дат.
+- Заводится окно или полноэкранный просмотр поверх страницы.
+- Шторку или окно что-то перекрывает, и хочется поднять им `z-index`.
+
+Панель правки записи в админке — это другое: там маршрут в своём аутлете, паттерн
+`entity-aside`.
+
+## Открывает служба, а не разметка рядом с кнопкой
+
+Компонент шторки — обычный элемент разметки. Он рисуется там, где написан, поэтому его
+`z-index` сравнивается только с соседями по этому месту. Липкая шапка размывает фон под собой —
+и всё, что написано внутри шапки, замкнуто в её слой.
+
+Открывает шторку служба окон кита — тем же вызовом открывается полноэкранный просмотр.
+Разметка уезжает к `<body>`, и сравнивать её становится не с чем.
+
+```typescript
+readonly #dialog: RtDialogService = inject(RtDialogService);
+
+readonly #sheetOpenedSource: Subject<RtDialogRef<string>> = new Subject<RtDialogRef<string>>();
+#sheetRef: RtDialogRef<string> | null = null;
+
+protected openLocalePicker(): void {
+    if (this.#sheetRef) {
+        return;
+    }
+
+    const data: ILocalePickerData = { locales: this.locales, value: this.currentLocale };
+    const ref: RtDialogRef<string> = this.#dialog.open<LocalePickerComponent, ILocalePickerData, string>(
+        LocalePickerComponent,
+        { data, panelClass: 'locale-picker-panel', backdropClass: 'locale-picker-backdrop' }
+    );
+    this.#sheetRef = ref;
+    this.#sheetOpenedSource.next(ref);
+}
+```
+
+Ответ шторки ждут подпиской из конструктора — подписываться в методе запрещает
+`angular-patterns`:
+
+```typescript
+this.#sheetOpenedSource
+    .pipe(
+        mergeMap((ref: RtDialogRef<string>): Observable<string | undefined> => ref.afterClosed()),
+        takeUntilDestroyed(this.#destroyRef)
+    )
+    .subscribe((code: string | undefined): void => {
+        this.#sheetRef = null;
+        if (code) {
+            this.onLocaleChange(code);
+        }
+    });
+```
+
+Ссылку обнуляют здесь, а не в обработчике кнопки: шторку закрывают ещё жестом вниз и нажатием
+мимо, и оба пути идут мимо кнопки.
+
+## Внутри шторки — только она сама
+
+Что показать, приходит токеном. Что выбрали, уходит вместе с закрытием. Своей кнопки у шторки
+нет: кнопку держит тот, кто шторку открывает.
+
+```typescript
+export interface ILocalePickerData {
+    readonly locales: readonly ISiteLocale[];
+    readonly value: string;
+}
+
+readonly #data: ILocalePickerData = inject<ILocalePickerData>(RT_DIALOG_DATA);
+readonly #dialogRef: RtDialogRef<string> = inject<RtDialogRef<string>>(RtDialogRef);
+
+protected confirm(): void {
+    this.#dialogRef.close(this.centeredLocale());
+}
+
+/** Закрыли, не подтвердив: значит, передумали — значение не меняем */
+protected onOpenChange(open: boolean): void {
+    this.open.set(open);
+    if (!open) {
+        this.#dialogRef.close();
+    }
+}
+```
+
+## Шторка приезжает снизу
+
+Служба поднимает её сразу открытой, и анимировать киту нечего: вместо движения гость видит
+подмену экрана. Поэтому открывают её на кадр позже:
+
+```typescript
+protected readonly open: WritableSignal<boolean> = signal<boolean>(false);
+
+constructor() {
+    afterNextRender((): void => {
+        this.open.set(true);
+    });
+}
+```
+
+`afterNextRender`, а не `ngAfterViewInit`: страницу отдаёт сервер, и разметка появляется позже.
+
+## Подложка
+
+Шторка сама затемняет фон и сама ловит нажатие мимо. Подложка окна поверх неё дала бы второе
+затемнение — фон стал бы вдвое темнее, чем у соседней шторки. Поэтому её делают прозрачной.
+Правило пишут в общий слой приложения: шторка уехала к `<body>`, и файл стилей компонента до
+неё не достаёт.
+
+```scss
+/* общий слой приложения; имя класса несёт приставку дерева */
+.locale-picker-backdrop {
+    background: transparent;
+}
+```
+
+Нажатие она ловит по-прежнему — закрытие по ней делает само окно.
+
+## Чем проверяется
+
+Скриншот тут не поможет: перекрытая шторка выглядит целой, а сборка и линт молчат. Спрашивают
+точку — кому достанется нажатие:
+
+```javascript
+const rect = button.getBoundingClientRect();
+document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+```
+
+Ответом должна быть сама кнопка. Мерить надо на стенде из прод-сборки и на узком экране —
+паттерн `browser-verification-measure`.
+
+В сквозном тесте перед замером дожидаются, пока шторка доедет: видимая кнопка ещё может
+двигаться, и координаты через кадр будут другими.
+
+```typescript
+await page.locator('[qa-dataid="locale-picker-sheet"] [qa-dataid="bottom-sheet-panel"]').evaluate(
+    (panel: Element): Promise<void> =>
+        new Promise<void>((resolve: () => void): void => {
+            if (panel.getBoundingClientRect().bottom <= window.innerHeight) {
+                resolve();
+
+                return;
+            }
+            panel.addEventListener('transitionend', (): void => resolve(), { once: true });
+        })
+);
+```
+
+## Частые промахи
+
+- **Шторка написана рядом со своей кнопкой в шапке.** Шапка размывает фон, и шторка замкнута в
+  её слой. Так нижняя панель накрыла шторку вместе с кнопкой подтверждения, и значение на
+  телефоне стало не сменить.
+- **Шапке подняли номер слоя.** Дефект уходит, шторка остаётся замкнутой в чужой слой:
+  следующий сосед с номером повыше накроет её снова.
+- **Шторку перенесли в другое место разметки.** То же самое: заработает, пока над новым местом
+  никто не поставит `transform`, `filter` или свой `z-index`.
+- **Правило подложки положили в стили компонента.** Подложка уехала к `<body>`, и правило до
+  неё не достаёт — писать надо в общий слой приложения.
+- **Ссылку на открытую шторку обнулили в обработчике кнопки.** Закрытие жестом и нажатием мимо
+  идёт мимо него, и второй раз шторка уже не откроется.
+- **Тест померил сразу после проверки видимости.** Шторка ещё едет, `elementFromPoint`
+  возвращает `null`, и тест краснеет на исправном коде.
+- **Образец искали по именам библиотеки, поверх которой собран кит.** Она лежит внутри кита, её
+  имён в дереве нет — искать надо по именам кита.

package/assets/patterns/task-flow-close.md

@@ -148,7 +148,27 @@ npm run check:docs    # пути, названные в текстах, суще
   выкачено» с тем, что работает месяц, — беззвучная ложь, тем убедительнее, чем старше.
 - **Номера сценариев при вливании не пересчитываются.** Идентификатор — ключ связи с тестами;
   сдвиг рвёт сверку у соседей, которых правка не касалась.
+- **«Что не входит» после вливания читается целиком, а не дописывается.** Договорённость несёт
+  свои границы, и при вливании они ложатся рядом с границами домена: половина повторяет уже
+  стоявшее другими словами, а строка «этого раздела ещё нет» становится ложью ровно той
+  работой, которая её вливает. Сверка спеков в этот раздел не смотрит вовсе. Снимается
+  дословный повтор и то, что работа сделала входящим.
+- **Шаги закрытия с владельцем не согласуются — они перечислены здесь.** Разбор работы
+  правилами входит в закрытие так же, как вливание договорённости и разбор папки; владелец
+  решает не то, запускать ли его, а что делать с находками. Ход, кончившийся таким вопросом,
+  отбивает гард разговора: за ход правила не читались, а ответ стоит в них. Спрашивается только
+  то, чего в правилах нет.
+- **Блок готового кода в паттерне стареет от чужой правки.** Он не привязан ни к чему: сверка
+  спеков читает утверждения правила, а пример под ними не читает вовсе. Два поля, ставших
+  обязательными в чужой работе, сделали пример в соседнем паттерне несобираемым — сам он при
+  этом не изменился ни на знак и в след задачи не попал, потому что ни одного слова той работы
+  в нём нет. Паттерн находится по имени правленого символа, а не по теме работы.
 - **Правило без привязки в спек домена не въезжает.** Кода, который его исполняет, нет —
   значит это намерение, и место ему в открытых вопросах домена, а не в правилах.
+- **Замысел линии работ правят только там, где вписывают «чем кончилась».** Границы линии и
+  порядок задач в ней при этом остаются прежними, а работа их уже нарушила: задача, решившая
+  читать спеки, оставила над собой границу «спеки — вторая очередь», и следующий исполнитель
+  прочитает её как действующую. Границы линии перечитываются целиком тем же заходом, что и
+  итог работы.
 - **Архив не обновляется после выкатки.** Уехавшее туда описывает день переезда, и правится
   оно только вместе с признанием, что описывало неверно.

package/assets/patterns/task-flow-resume.md

@@ -102,5 +102,10 @@ git log --oneline origin/main..HEAD
   несохранённым и почему» — единственное, по чему это видно, пока отчёта нет.
 - **Подтверждение — вывод команды или замер, а не пересказ.** «Проверил, работает» через
   заход неотличимо от «казалось, что работает».
+- **Число из передачи пересчитывается до того, как на нём что-то делят.** Передача описывает
+  день, когда её писали, лежит вне дерева, и не читает её ни одна проверка. Оценка «работы
+  вдвое больше предыдущей» при пересчёте на текущем коммите не подтвердилась: по числу
+  утверждений объёмы оказались почти равны. Деление работы по чужой оценке делит не то, и
+  владельцу называются свои числа.
 - **Доэтапное отделяется от своего.** Красное, найденное по дороге и не этой работой
   сделанное, помечается таковым сразу: иначе следующий заход примет его за свою поломку.

package/assets/patterns/translations-content.md

@@ -0,0 +1,107 @@
+---
+name: translations-content
+kind: pattern
+rule: translations
+description: Паттерн правила translations. Брать при работе с переводами содержимого записи — производный перевод при сохранении, запись локали руками через язык админки, разбор отказа провайдера, сброс кэша отданных страниц. Не брать для подписей интерфейса — это паттерн translations-key.
+---
+
+# Перевод содержимого записи
+
+Паттерн правила `translations`. Что при этом должно быть верно — закон
+`docs/constitution/application/locales.md`.
+
+## Когда брать
+
+- Владелец правит тексты записи, и остальные локали должны догнать.
+- Админка ответила, что сохранила на языке ввода, а перевод на остальные не удался.
+- Локаль надо заполнить руками: провайдер недоступен, а страница на этом языке нужна сегодня.
+- Проверяется, что отданная страница показывает свежий текст.
+
+## Перевод идёт сам, и просить его нечем
+
+Кнопки «перевести» нет. Владелец печатает на своём языке, а процедура сохранения зовёт перевод
+до транзакции и кладёт в хранилище уже все локали. Локаль ввода приезжает полем запроса и
+берётся из языка админки, а не из браузера гостя.
+
+В партию идёт не всё подряд: сборщик отбрасывает строку, чей исходный текст не менялся **и**
+которая переведена на все целевые локали. Отсюда два следствия:
+
+- сохранение записи без правки текстов провайдера не зовёт вовсе — перестановка изображения или
+  правка числа ничего не стоит;
+- строка, у которой хоть одна локаль пуста, поедет на перевод при первом же сохранении, без
+  правки самого текста.
+
+## Локаль пишется руками через язык админки
+
+Табов локалей в форме нет, и это не упущение: поле одно, а какая локаль за ним стоит, решает
+язык интерфейса. Значит записать перевод руками — это переключить язык в шапке админки и
+заполнить те же поля.
+
+Путь этот не аварийный: пока у провайдера пуст счёт, он и есть обычный порядок, и каждый
+видимый текст заводится по разу на локаль. Считать его временным и ждать автоперевода не надо.
+
+Порядок такой:
+
+1. Меню владельца в шапке → выбрать язык.
+2. Открыть запись. Текстовые поля покажут текст **этой** локали; пустые они там, где локали у
+   записи нет.
+3. Заполнить и сохранить.
+
+Соседние локали при этом целы: черновик пишет в карту по коду локали, а остальные ключи уезжают
+в запрос как пришли. Отказ провайдера ничего не портит — в хранилище ложится ровно то, что
+прислала форма.
+
+Записанное руками потом не перетирается: у поля заполнены все локали, и сборщик партии больше
+не берёт его, пока владелец не изменит исходный текст.
+
+Собирать вызов сохранения скриптом для этого не надо, и правило это прямо запрещает: черновик
+перезаписывает запись целиком, а вложенная запись, не попавшая в список, удаляется вместе со
+своими связями.
+
+## Отказ провайдера читается не по экрану
+
+Владельцу показывается одна фраза без причины. Причина живёт в логах строкой своего контекста:
+
+```bash
+docker compose -f <состав прода> --env-file <файл окружения> logs api --since 30m \
+    | grep -i translation
+```
+
+Строка несёт код ответа, но не текст: клиент бросает отказ по коду, не читая тела. Что именно
+ответил провайдер, спрашивается у него напрямую тем же ключом; для разового вызова его берут
+руками — приложение эту переменную не читает, но значение там то же, что владелец завёл в
+админке. Отказ по деньгам означает пустой счёт, а не сломанный ключ: список моделей при этом
+отдаётся, и строка интеграции показывает «работает». Где лежит сам ключ и почему проба
+зелёная — паттерн `git-workflow-secrets`.
+
+## Отданная страница показывает прежний текст, пока не сброшен кэш
+
+Записанный перевод виден в хранилище сразу, а гостю — нет: страницы лежат в кэше прокси. На
+проде он сбрасывается так же, как на стенде:
+
+```bash
+docker exec <контейнер прокси> sh -c 'rm -rf /var/cache/nginx/site/*; nginx -s reload'
+```
+
+Сверяется отданной разметкой по каждой правленой локали, а не взглядом на админку:
+
+```bash
+for l in <локали>; do
+    printf '%-8s ' "$l"
+    curl -sL "https://<адрес сайта>/$l/" | grep -oE '<meta name="description" content="[^"]{0,80}'
+done
+```
+
+## Частые промахи
+
+- **Проверять результат в админке.** Форма показывает то, что в хранилище, и молчит о кэше: три
+  локали были записаны и проверены, а сайт ещё полчаса отдавал прежний текст на всех.
+- **Считать, что перевода нет, раз пришло предупреждение.** Прежние локали остаются на месте;
+  пустой окажется только та, которой не было раньше.
+- **Писать в хранилище напрямую.** Запись в боевое хранилище запрещена совсем, а колонка со
+  свободной структурой выглядит безобидной целью — тексты правятся через админку, и другого
+  пути у них нет.
+- **Переводить имя собственное.** Оно остаётся как есть во всех локалях: так велит словарь в
+  задании провайдеру, и рукописный перевод обязан вести себя так же.
+- **Копировать одно письмо языка в другое.** Упрощённое и традиционное письмо — разные локали и
+  разное письмо; посимвольная копия простояла на проде, и гость читал чужие иероглифы.

package/assets/patterns/translations-key.md

@@ -27,7 +27,7 @@ description: Паттерн правила translations. Брать, когда
 | `admin.json`  | админ-панель                |
 | `mail.json`   | письма и документ-основание |
 
-Локалей восемь: `en`, `ru`, `de`, `zh-Hans`, `zh-Hant`, `ko`, `th`, `hi`. Ключ заводится во
+Набор локалей перевода назван в `implementation.md` правила. Ключ заводится во
 всех — пустое значение считается пропуском, а не переводом.
 
 ## Подстановка

package/assets/rules/angular-patterns.md

@@ -40,6 +40,11 @@ description: Правило под «Закон о фронтовом прило
   объявлена подписка.
 - **Источник действия носит суффикс `Source` в имени.** Иначе поток и значение в коде
   неотличимы, и `next` уходит не туда.
+- **Вызов сервиса внутри `computed` зависимостью не становится.** Производное значение следит
+  только за прочитанными сигналами, а обычный метод сигналом не является: значение остаётся
+  таким, каким было в момент первого счёта. Текущий язык, текущее владение, текущий признак
+  среды читаются сигналом службы — тогда производное пересобирается вместе с их сменой. Ни
+  сборка, ни линтер этого не видят.
 - **Списочный стор наследует общую основу.** Записи, страница, порядок, условия отбора, строка
   поиска и конфиг выборки уже там, и наследнику остаются четыре строки.