@rt-tools/agent-kit 0.3.0 → 0.4.0

package/assets/patterns/ownership-scope-resolve.md

@@ -0,0 +1,69 @@
+---
+name: ownership-scope-resolve
+kind: pattern
+rule: ownership-scope
+description: Паттерн правила ownership-scope. Брать, когда процедура принимает идентификатор владеющей сущности — готовое разрешение одной и всех действующих, коды отказа на каждый случай, условие отбора вместо своего поля запроса. Не брать для объявления доступа к процедуре — это паттерн permissions-procedure.
+---
+
+# Разрешение владеющей сущности в процедуре
+
+Паттерн правила `ownership-scope`. Что при этом должно быть верно — закон
+`docs/constitution/application/ownership.md`.
+
+## Когда брать
+
+- Процедура принимает идентификатор владеющей сущности.
+- Экран или сводка отвечает сразу по всем действующим.
+- Заводится новый домен, записи которого принадлежат владеющей сущности.
+
+## Одна сущность
+
+```typescript
+const ownerId: string = await resolveRequestedOwner(this.#db, request.ownerId);
+```
+
+Обёртка сама разбирает случаи и переводит их в отказ:
+
+| Что пришло                                            | Что происходит            |
+| ----------------------------------------------------- | ------------------------- |
+| пусто, действующая одна                               | берётся она               |
+| пусто, действующих две и больше                       | `Code.InvalidArgument`    |
+| пусто, действующих нет вовсе                          | `Code.FailedPrecondition` |
+| названная явно, есть — хоть действующая, хоть скрытая | берётся она               |
+| названная явно, такой нет                             | `Code.NotFound`           |
+
+Своего разбора не заводить: чистая функция разбирает случай, обёртка ходит в хранилище. Вторая
+реализация того же правила однажды уже жила у обработчика статистики соседнего домена и успела
+разойтись порядком выборки.
+
+## Все действующие
+
+Там, где показана сводка, пустой идентификатор означает все действующие:
+
+```typescript
+const ownerIds: string[] = await resolveRequestedOwners(this.#db, request.ownerId);
+```
+
+Так отвечают списки, статистика и дашборд.
+
+## Отбор вместо своего поля запроса
+
+У списка, переведённого на общую выборку, сущность приходит условием отбора, а не отдельным
+полем: прежний номер поля в контракте помечен `reserved`.
+
+```
+reserved 4;
+reserved "owner_id";
+```
+
+## Частые промахи
+
+- Свой разбор пустого идентификатора в обработчике: он разойдётся с общим при первой же правке.
+- Один и тот же код отказа на «действующих нет» и «такой сущности нет»: для вызывающего это
+  разные случаи.
+- Подстановка скрытой, когда действующих нет: скрытая вместо отсутствующей действующей не
+  берётся.
+- Общая настройка, действующая сразу на все: заведение второй не должно менять поведение
+  первой.
+- Новое поле идентификатора рядом с выборкой у списка: отбор, живущий отдельно, не виден ни
+  стору, ни адресу.

package/assets/patterns/permissions-procedure.md

@@ -2,68 +2,70 @@
 name: permissions-procedure
 kind: pattern
 rule: permissions
-description: Паттерн правила permissions. Брать при заведении обработчика серверной стороны и при закрытии раздела интерфейса — метки доступа, отбивка без входа и без права, декларация пункта меню с правом и признаком незавершённости.
+description: Паттерн правила permissions. Брать при заведении процедуры Connect и при закрытии раздела админки — готовые декораторы доступа, отбивка без входа и без права, декларация пункта меню с правом и флагом. Не брать для устройства самого меню — это правило navigation.
 ---
 
 # Объявление доступа
 
-Паттерн правила `permissions`. Что при этом должно быть верно — закон `{{lawsDir}}/access.md`.
+Паттерн правила `permissions`. Что при этом должно быть верно — закон
+`docs/constitution/application/access.md`.
 
 ## Когда брать
 
-- Заводится обработчик серверной стороны.
-- Раздел интерфейса закрывается правом.
-- Обработчик должен отвечать гостю.
+- Заводится процедура Connect.
+- Раздел админки закрывается правом.
+- Процедура должна отвечать гостю.
 
-## Метка на классе обработчика
+## Декоратор на классе процедуры
 
 Объявление ровно одно; без него приложение не поднимается:
 
 ```typescript
 @Injectable()
 @ConnectProcedure()
-@RequiresPermission('<ресурс>:<действие>')
-export class LinkEntityProcedure implements IConnectProcedure<typeof DomainService.method.linkEntity> {
-    public readonly method: typeof DomainService.method.linkEntity = DomainService.method.linkEntity;
+@RequiresPermission('chat:manage')
+export class LinkBookingProcedure implements IConnectProcedure<typeof ChatService.method.linkBooking> {
+    public readonly method: typeof ChatService.method.linkBooking = ChatService.method.linkBooking;
 }
 ```
 
-| Метка                            | Кому доступно                                     |
-| -------------------------------- | ------------------------------------------------- |
-| требование права                 | вошедшему с этим правом                           |
-| требование входа                 | любому вошедшему; так живут профиль и выбор языка |
-| публичный доступ                 | гостю без входа                                   |
-| публичный доступ с чтением входа | гостю, но токен читается, если он есть            |
+| Декоратор                                    | Кому доступно                                     |
+| -------------------------------------------- | ------------------------------------------------- |
+| `@RequiresPermission('<ресурс>:<действие>')` | вошедшему с этим правом                           |
+| `@RequiresAuth('<причина>')`                 | любому вошедшему; так живут профиль и выбор языка |
+| `@PublicProcedure('<причина>')`              | гостю без входа                                   |
+| `@OptionalAuthProcedure('<причина>')`        | гостю, но токен читается, если он есть            |
 
-Аргумент — причина для читателя кода. Ни в ответ, ни в журнал она не уходит.
+Аргумент — причина для читателя кода. Ни в ответ, ни в лог она не уходит.
 
 ## Отбивка
 
-Перехватчик отвечает до тела обработчика:
+Перехватчик отвечает до тела процедуры:
 
-- нет входа там, где вход нужен, — неаутентифицирован;
-- вход есть, права нет — отказ в доступе;
-- обработчик, о котором перехватчик ничего не знает, — тоже отказ, а не пропуск.
+- нет входа там, где вход нужен, — `Code.Unauthenticated`;
+- вход есть, права нет — `Code.PermissionDenied`;
+- процедура, о которой перехватчик ничего не знает, — тоже отказ в доступе, а не пропуск.
 
-Сам обработчик решения о допуске не принимает.
+Обработчик решения о допуске не принимает.
 
-## Раздел интерфейса
+## Раздел админки
 
-Пункт меню и адрес закрываются одной декларацией: шапка берёт из неё подписи и адреса, страж —
-права. Второго объявления этой связи не заводится.
+Пункт меню и адрес закрываются одной декларацией в
+`libs/admin/common/container/util`: шапка берёт из неё подписи и адреса, гвард — права.
+Второго объявления этой связи не заводится.
 
-Закрытие двухслойное: право пользователя и признак незавершённости раздела. Пункт с признаком
-объявляется без прав и без адреса — право открывает экран, а экрана нет. Появится экран —
-признак снимается, права добавляются.
+Гейтинг двухслойный: право пользователя и флаг раздела. Пункт с флагом объявляется без прав и
+без адреса — право открывает экран, а экрана нет. Появится экран — флаг снимается, права
+добавляются.
 
 ## Частые промахи
 
-- **Два объявления доступа на одном обработчике:** приложение не поднимется, и увидено это
-  будет только при запуске.
-- **Проверка права внутри тела:** право проверяется до тела.
-- **Своё объявление прав рядом с маршрутами:** оно разойдётся с декларацией меню, и получится
+- Два объявления доступа на одной процедуре: приложение не поднимется, и увидено это будет
+  только при запуске.
+- Проверка права внутри `handle`: право проверяется до тела.
+- Своё объявление прав рядом с маршрутами: оно разойдётся с декларацией меню, и получится
   «пункта не видно, а страница открывается».
-- **Страж, повешенный на защищённую группу целиком:** он отрабатывает один раз за загрузку
+- Гвард, повешенный на защищённую группу целиком: он отрабатывает один раз за загрузку
   страницы и переходов между разделами не видит.
-- **Ожидание прав, которое роняется на отказе запроса:** с неизвестными правами не закрывается
+- Ожидание прав, которое роняется на отказе запроса: с неизвестными правами не закрывается
   ничего, и пустая шапка выхода владельцу не оставляет.

package/assets/patterns/platform-access-di.md

@@ -2,23 +2,28 @@
 name: platform-access-di
 kind: pattern
 rule: platform-access
-description: Паттерн правила platform-access. Брать, когда в код заходит окно, документ или проверка среды — внедрение токенов, приведение к глобальной области, окно параметром в чистой функции, работа с разметкой после первой отрисовки. Не брать на серверной стороне.
+description: Паттерн правила platform-access. Брать, когда в код заходит окно, документ или проверка среды — готовые инжекты токенов, приведение к Window & typeof globalThis, окно параметром в чистой функции, инициализация DOM после первой отрисовки. Не брать под libs/api и apps/api.
 ---
 
 # Окно, документ и проверка среды
 
 Паттерн правила `platform-access`. Что при этом должно быть верно — закон
-`{{lawsDir}}/frontend-application.md`.
+`docs/constitution/frontend-application.md`.
 
 ## Когда брать
 
-- В компонент, службу или директиву заходит окно, документ или проверка среды.
-- Появляется работа с разметкой, которой нельзя случиться до первой отрисовки.
+- В компонент, сервис или директиву заходит `window`, `document` или проверка среды.
+- Появляется работа с DOM, которой нельзя случиться до первой отрисовки.
 - Чистой функции нужен доступ к окну.
 
-## Внедрение
+## Инжекты
 
 ```typescript
+import { DOCUMENT } from '@angular/common';
+import { inject, Injectable } from '@angular/core';
+
+import { PlatformService, WINDOW } from '@rt-tools/core';
+
 @Injectable({ providedIn: 'root' })
 export class SomeService {
     readonly #document: Document = inject(DOCUMENT);
@@ -27,44 +32,53 @@ export class SomeService {
 }
 ```
 
-## Когда нужен тип глобальной области
+## Когда нужен `Window & typeof globalThis`
 
-Интерфейс окна не описывает глобальные конструкторы и пространства имён — наблюдателей
-пересечения и размера, объекты внешних карт. Токен отдаёт тот же самый объект, поэтому тип
-уточняется приведением, и рядом ставится комментарий с причиной:
+Интерфейс `Window` не описывает глобальные конструкторы и неймспейсы —
+`IntersectionObserver`, `ResizeObserver`, `google` из `@types/google.maps`. Токен отдаёт тот же
+самый объект, поэтому тип уточняется приведением, и рядом ставится комментарий с причиной:
 
 ```typescript
-// Конструкторы наблюдателей объявлены на глобальной области, а не на интерфейсе окна —
-// токен отдаёт тот же объект, тип лишь уточняется.
+// Конструкторы вроде IntersectionObserver объявлены на globalThis, а не на
+// интерфейсе Window — токен отдаёт тот же объект, тип лишь уточняется.
 readonly #window: Window & typeof globalThis = inject(WINDOW) as Window & typeof globalThis;
 ```
 
 ## Чистая функция принимает окно параметром
 
-В файлах чистой логики внедрения нет, и глобал внутрь не тянется:
+В `*.logic.ts` и `*.util.ts` нет DI, и глобал внутрь не тянется:
 
 ```typescript
 export function mapsReady(windowRef: Window & typeof globalThis): boolean {
-    return typeof windowRef.maps?.importLibrary === 'function';
+    return typeof windowRef.google?.maps?.importLibrary === 'function';
 }
 ```
 
-Внедряет его вызывающий компонент.
+Инжектит его вызывающий компонент.
 
 ## Проверка среды и первая отрисовка
 
-Среда спрашивается у службы платформы, а работа с разметкой уходит в крючок первой отрисовки.
-Проверка «глобал определён» не годится: она верна случайно и ломается на первой же среде, где
-глобал подставлен.
+```typescript
+if (!this.#platform.isPlatformBrowser) {
+    return;
+}
+```
+
+```typescript
+afterNextRender((): void => {
+    // работа с DOM, которой не должно быть до первой отрисовки
+});
+```
+
+`typeof window !== 'undefined'` не годится: проверка по наличию глобала верна случайно.
 
 ## Частые промахи
 
-- **Проверка среды прямым обращением к признаку платформы** вместо службы.
-- **Проверка среды вокруг чтения и записи в хранилище:** служба хранилища и так уходит в память
-  вне браузера, и такое условие — мёртвый код.
-- **Окно полем класса в службе, обязанной работать без разметки вовсе:** там оно берётся внутри
-  метода под проверкой среды.
-- **Правка добавила окно в службу, создающуюся на подъёме, а проверили одной сборкой:** падение
+- `isPlatformBrowser(inject(PLATFORM_ID))` вместо `PlatformService`.
+- Проверка среды вокруг чтения и записи в хранилище: `StorageService` и так уходит в память
+  вне браузера, и такой `if` — мёртвый код.
+- `WINDOW` полем класса в сервисе, который обязан работать без DOM вообще: там окно берётся
+  внутри метода под проверкой среды.
+- Правка добавила `WINDOW` в сервис, создающийся на подъёме, а проверили одной сборкой: падение
   видно только на поднятом сервере отдачи страниц.
-- **Приведение без комментария:** в переводчиках моделей приведение запрещено, и строка
-  читается как нарушение.
+- Приведение без комментария: в мапперах приведение запрещено, и строка читается как нарушение.

package/assets/patterns/pricing-quote.md

@@ -0,0 +1,71 @@
+---
+name: pricing-quote
+kind: pattern
+rule: pricing
+description: Паттерн правила pricing. Брать при правке расчёта цены, механик скидки, работы с курсом валют и сумм в письмах и документах — где округлять, как выбирается одна скидка, что кладётся в бронь. Не брать для доступа к процедурам цен — это паттерн permissions-procedure.
+---
+
+# Расчёт цены
+
+Паттерн правила `pricing`. Что при этом должно быть верно — закон
+`docs/constitution/application/money.md`.
+
+## Когда брать
+
+- Правится расчёт цены или механика скидки.
+- В код заходит сумма в чужой валюте.
+- Сумма попадает в заказ, письмо, документ или сводку.
+
+## Всё считается один раз
+
+Расчёт живёт в `calculateQuote` и отдаёт готовые числа: ночи, подытог, скидку, итог, признак
+минимального срока. Показ, письмо и запись в базу берут одни и те же числа, а не пересчитывают
+их каждый у себя.
+
+```typescript
+const quote: IQuoteResult = calculateQuote({
+    checkIn,
+    checkOut,
+    basePriceThb,
+    defaultMinNights,
+    seasons,
+    lengthDiscounts,
+    promoCode,
+});
+```
+
+## Одна скидка — наибольшая
+
+Механики считаются по отдельности, а выбор между ними один:
+
+```typescript
+const best: IDiscountCandidate | undefined = bestCandidateOf([
+    lengthCandidateOf(nights, input, subtotalThb),
+    promoCandidateOf(input.promoCode, subtotalThb),
+]);
+```
+
+При равных суммах побеждает промокод: владелец выдал его адресно, а скидка за длительность
+досталась бы гостю и без него. Новая механика добавляется третьим кандидатом в тот же вызов, а
+не отдельным вычитанием из итога.
+
+## Чужая валюта — на показ
+
+В заказе лежат сумма в валюте хранения и код валюты, в которой гость смотрел цену. Само число в чужой
+валюте не хранится нигде:
+
+```typescript
+export const SUPPORTED_QUOTE_CURRENCIES: readonly string[] = ['USD', 'RUB', 'EUR', 'CNY'];
+```
+
+Курс тянется по расписанию и кэшируется в хранилище. Курса нет — сумма показывается в валюте хранения без
+пересчёта.
+
+## Частые промахи
+
+- Округление на показе: сумма гостя, сумма письма и сумма в базе разойдутся на единицы.
+- Сложение двух скидок: владелец таких сумм не закладывал, и объяснить гостю итог нечем.
+- Сохранённое число в чужой валюте: оно устареет вместе с курсом.
+- Справочная сумма, подписанная как сумма к оплате, — оплата идёт в валюте хранения.
+- Письмо в валюте, отличной от той, что гость выбирал на сайте: оно читается как другая цена.
+- Дробная часть в сумме: единица хранения целая.

package/assets/patterns/reuse-first-extend.md

@@ -2,39 +2,39 @@
 name: reuse-first-extend
 kind: pattern
 rule: reuse-first
-description: Паттерн правила reuse-first. Брать, когда готового в источнике вида или в базовом классе не хватило — что проверить перед тем, как писать своё, как расширить готовое, как объявить разовое отступление маркером и когда его снимать.
+description: Паттерн правила reuse-first. Брать, когда готового в ките или в базовом классе не хватило — что проверить перед тем, как писать своё, как расширить готовое, как объявить разовое отступление маркером native-ok и когда его снимать.
 ---
 
 # Готового не хватило
 
-Паттерн правила `reuse-first`. Что при этом должно быть верно — закон `{{lawsDir}}/reuse-first.md`.
+Паттерн правила `reuse-first`. Что при этом должно быть верно — закон
+`docs/constitution/reuse-first.md`.
 
 ## Когда брать
 
-Готовый компонент или базовый класс не покрывает случай, и рука тянется написать своё рядом.
+Компонент кита или базовый класс не покрывает случай, и рука тянется написать своё рядом.
 
 ## Сначала — проверить, что действительно не хватает
 
 ```bash
-grep -c "export" <барель источника вида>
-grep -rn "<похожий приём>" <каталоги кода> --include='*.html' | head
+grep -n "export" @rt-tools/ui-kit-v2/src/index.ts | wc -l
+grep -rn "<похожий приём>" libs/admin libs/site --include='*.html' | head
 ```
 
-Источник вида большой, и большинства его компонентов нет ни в одной таблице. Соседний домен
-читается целиком: приём, который кажется новым, обычно уже написан — и переименованный при
-переносе он перестаёт узнаваться.
+Кит большой, и большинства его компонентов нет ни в одной таблице. Соседний домен читается
+целиком: приём, который кажется новым, обычно уже написан — и переименованный при переносе он
+перестаёт узнаваться.
 
-Частые подмены, которые находятся при чтении: готовый мерцающий заполнитель вместо своего,
-готовый диалог вместо своей вуали, готовое сообщение вместо своей области оповещения.
+Частые подмены, которые находятся при чтении: `<префикс>-skeleton` вместо своего мерцания,
+`<префикс>-dialog` вместо своей вуали, `<префикс>-message` вместо своего `role="alert"`.
 
 ## Расширять, а не клонировать
 
-Недостающий вариант заводится **в источнике вида или в базовом классе**, и его видят остальные
-экраны.
+Недостающий вариант заводится **в ките или в базовом классе**, и его видят остальные экраны.
 
 ```
-✗ <домен>/ui/my-dialog/          клон «почти как готовый»
-✓ <источник вида>/dialog/        новый вариант у готового
+✗ libs/admin/<домен>/ui/my-dialog/        клон «почти как китовый»
+✓ @rt-tools/ui-kit-v2/src/lib/components/dialog/   новый вариант у готового
 ```
 
 Клон, написанный рядом, забирает правки на себя и расходится с оригиналом с первой же.
@@ -42,31 +42,31 @@ grep -rn "<похожий приём>" <каталоги кода> --include='*.
 
 ## Свой примитив — только с одобрения владельца
 
-Спрашивается до того, как написан первый файл. То же относится к своей основе и к своему
-оформлению на месте.
+Спрашивается до того, как написан первый файл. То же относится к своей базе и к своему
+инлайновому стилю.
 
 ## Разовое отступление объявляется маркером
 
 ```html
-<!-- <маркер>: в источнике вида нет поля с маской телефона, заведено задачей -->
+<!-- native-ok: в ките нет поля с маской телефона, заведено задачей <КЛЮЧ>-000 -->
 <input type="tel" qa-dataid="phone-input" />
 ```
 
-Маркер ставится в той же строке и объясняет, **чего именно нет в готовом**. «Эти строки были
-здесь раньше» причиной не считается: гард вычёркивает из проверяемого текста то, что уже лежит
-в файле, поэтому отказ означает новый текст.
+Маркер `native-ok` ставится в той же строке и объясняет, **чего именно нет в ките**. «Эти
+строки были здесь раньше» причиной не считается: гард вычёркивает из проверяемого текста то,
+что уже лежит в файле, поэтому отказ означает новый текст.
 
 Сверка идёт без отступов — при переезде блок меняет отступ, оставаясь тем же кодом.
 
 ## Снятие отступления
 
-Когда недостающее появилось в готовом, маркер снимается вместе с обходом. Комментарий,
+Когда недостающее появилось в ките, маркер снимается вместе с обходом. Комментарий,
 оправдывающий отклонение, держит это отклонение на себе: пока объяснение выглядит убедительно,
 его не трогают.
 
 ## Частые промахи
 
-- Своё написано до чтения источника вида и соседнего домена.
+- Своё написано до чтения кита и соседнего домена.
 - Клон рядом вместо нового варианта у готового.
 - Маркер поставлен без объяснения, чего не хватает.
 - Маркер оставлен после того, как готовое появилось.

package/assets/patterns/seo-page.md

@@ -2,91 +2,103 @@
 name: seo-page
 kind: pattern
 rule: seo
-description: Паттерн правила seo. Брать, когда правится разметка публичной страницы, заводится новый маршрут или новая страница должна попасть в карту сайта — вызов общей службы тегов, ветки локалей в маршрутах, запись в карте сайта. Не брать для проверки отданной разметки — это паттерн seo-verify.
+description: Паттерн правила seo. Брать, когда правится разметка страницы публичного сайта, заводится новый маршрут или новая страница должна попасть в карту сайта — готовый вызов PropertySeoService, ветки локалей в app.routes.ts, строка в sitemap. Не брать для проверки отданной разметки — это паттерн seo-verify.
 ---
 
-# Разметка публичной страницы
+# Разметка страницы публичного сайта
 
-Паттерн правила `seo`. Что при этом должно быть верно — закон `{{lawsDir}}/search-visibility.md`.
+Паттерн правила `seo`. Что при этом должно быть верно — закон
+`docs/constitution/application/search-visibility.md`.
 
 ## Когда брать
 
-- Правится шаблон публичной страницы, её заголовок, описание или картинка для соцсетей.
-- Заводится новый публичный маршрут.
-- Появилась страница, которая должна попасть в карту сайта.
+- Правится шаблон страницы сайта, её заголовок, описание или картинка для соцсетей.
+- Заводится новый маршрут сайта.
+- Появилась страница, которая должна попасть в `sitemap.xml`.
 
-## Разметку ставит служба, а не шаблон
+## Разметку ставит сервис, а не шаблон
 
-Страница собирает данные и одним вызовом отдаёт их общей службе тегов. Своих тегов в шаблоне не
-заводить: они не помечены и потому не переписываются при переходе — тег от прошлой страницы
-переживёт следующую.
+Страница собирает данные и одним вызовом отдаёт их `PropertySeoService`. Своих `<meta>` в
+шаблоне не заводить: они не помечены `data-<префикс>-seo`, не переписываются при переходе и
+переживут смену страницы.
+
+Образец — `property-page.component.ts:#applySeo`:
 
 ```typescript
-readonly #seo: PageSeoService = inject(PageSeoService);
+readonly #seo: PropertySeoService = inject(PropertySeoService);
 
 constructor() {
     effect((): void => this.#applySeo());
 }
 
 #applySeo(): void {
-    const entity: IEntity.State | null = this.entity();
-    if (!entity) {
+    const property: IProperty.State | null = this.property();
+    if (!property) {
         return;
     }
 
+    const name: string = this.propertyName();
+    const cover: IPhotoView | null = this.coverDesktop();
+
     this.#seo.apply({
-        entity,
-        pageTitle: this.title(),
-        description: entity.shortDescription || this.#descriptionFallback(),
-        ogImageUrl: this.cover() ? ogUrl(this.cover()) : this.#brandImage(),
+        property,
+        name,
+        pageTitle: name ? `${name} — ${this.#titleSuffix()}` : this.#titleSuffix(),
+        description: property.shortDescription || this.#descriptionFallback(),
+        ogImageUrl: cover ? photoOgUrl(cover.baseUrl) : `${SITE_ORIGIN}/${BRAND_OG_IMAGE}`,
+        ogImageAlt: cover ? cover.alt : name,
+        ogImageWidth: OG_IMAGE_WIDTH,
+        ogImageHeight: OG_IMAGE_HEIGHT,
         locale: this.#localeId,
     });
 }
 ```
 
-Вызов идёт из эффекта, а не из конструктора напрямую: запись приходит реактивным значением, и
-на первом кадре её ещё нет. Ранний выход по пустой записи обязателен — без него разметка встала
-бы на пустых значениях и второй раз уже не переписалась бы.
+Вызов идёт из `effect`, а не из конструктора напрямую: объект приходит сигналом, и на первом
+кадре его ещё нет. Ранний выход по пустому объекту обязателен — без него разметка встала бы на
+пустых значениях и второй раз уже не переписалась бы.
 
-У картинки есть запасной вариант: запись без обложки отдаёт брендовый кадр того же формата,
+У картинки есть запасной вариант: объект без обложки отдаёт брендовое изображение того же формата,
 иначе превью в соцсети пустует.
 
 ## Новый маршрут заводится веткой на каждую локаль
 
-Ветки собираются из списка локалей; локаль по умолчанию своей ветки не имеет — она отдаётся из
-корня.
+Ветки собирает `apps/site/src/app/app.routes.ts` из `LOCALE_CODES`. Локаль по умолчанию своей
+ветки не имеет — она отдаётся из корня.
 
 ```typescript
 export const appRoutes: Route[] = [
     ...LOCALE_CODES.filter((code: ELocale): boolean => code !== DEFAULT_LOCALE).map((code: ELocale): Route => ({
         path: code,
-        children: publicRoutes,
+        children: propertyRoutes,
     })),
-    ...publicRoutes,
+    ...propertyRoutes,
 ];
 ```
 
-Новый путь дописывается в общий набор — тогда он появляется во всех ветках сразу. Ветки
-перечислены явными кодами, а не параметром: иначе первый же сегмент адреса был бы принят за
-язык.
+Новый путь дописывается в `propertyRoutes` — тогда он появляется во всех восьми ветках сразу.
+Ветки перечислены явными кодами, а не `:locale`: иначе `/<адрес страницы>` был бы принят за
+язык, а не за адрес объекта.
 
 ## Страница попадает в карту сайта явно
 
-Карта строится из записей, а не из маршрутов, и новая страница сама туда не попадёт. Правка
-идёт вместе со спекой на сборщик карты.
+Карта строится из объектов, а не из маршрутов, и новая страница сама туда не попадёт. Записи
+собирает `buildSitemap` (слой `util` домена страницы объекта), отдаёт обработчик
+`/sitemap.xml` в `apps/site/src/server.ts`. Правка идёт вместе со спекой в
+`sitemap.util.spec.ts`.
 
 ## Тексты идут из словарей
 
-Заголовок и описание собираются из переведённых значений и заводятся во всех локалях. Без
-перевода они уезжают в выдачу на одном языке, и заметно это только в чужой локали.
+`pageTitle` и `description` собираются из переведённых значений и заводятся во всех восьми
+локалях. Без перевода они уезжают в выдачу по-английски, и заметно это только в чужой локали.
 
 ## Частые промахи
 
-- **Тег в шаблоне вместо вызова службы** — он не помечен и переживёт переход.
-- **Вызов без раннего выхода по пустой записи** — разметка встаёт на пустых значениях.
-- **Новый путь дописан мимо общего набора** — работает только в локали по умолчанию, остальные
-  адреса отдают отказ.
-- **Свой разбор адреса вместо общего** — теряется всё после второго знака вопроса, и источник
-  обращения считается неверно.
-- **Правка разметки без проверки на прод-сборке:** на сервере разработки теги ставит другой
-  путь. Проверка описана паттерном `seo-verify`.
+- `<meta>` в шаблоне вместо вызова сервиса — тег не помечен `data-<префикс>-seo` и переживёт переход.
+- Вызов без раннего выхода по пустому объекту — разметка встаёт на пустых значениях.
+- Новый путь дописан мимо `propertyRoutes` — работает только в локали по умолчанию,
+  `/de/<путь>` отдаёт 404.
+- Свой разбор адреса вместо `splitRequestUrl` — теряется всё после второго `?`, и источник
+  заявки считается неверно.
+- Правка разметки без проверки на прод-сборке: в дев-сервере теги ставит не тот путь. Проверка
+  описана паттерном `seo-verify`.