@rt-tools/agent-kit 0.3.0 → 0.4.0

package/assets/patterns/angular-patterns-state.md

@@ -2,45 +2,50 @@
 name: angular-patterns-state
 kind: pattern
 rule: angular-patterns
-description: Паттерн правила angular-patterns. Брать при объявлении состояния и потоков в классе фронтового каркаса — реактивные входы и выходы, производные значения, состояние службы, долгоживущая подписка с источником действия. Не брать для раскладки файла компонента — это паттерн component-structure-new.
+description: Паттерн правила angular-patterns. Брать при объявлении состояния и потоков в классе Angular — готовые сигналы, производные значения, состояние сервиса, долгоживущая подписка с источником действия. Не брать для раскладки файла компонента — это правило component-structure.
 ---
 
 # Состояние и потоки
 
 Паттерн правила `angular-patterns`. Что при этом должно быть верно — закон
-`{{lawsDir}}/frontend-application.md`.
+`docs/constitution/frontend-application.md`.
 
 ## Когда брать
 
-- Объявляется состояние компонента или службы.
+- Объявляется состояние компонента или сервиса.
 - Появляется поток, на который надо подписаться.
 - Значение считается из другого значения.
 
-## Реактивные входы и выходы
+## Сигнальный API входов и выходов
 
 ```typescript
 public readonly data: InputSignal<Item[]> = input.required<Item[]>();
-public readonly isNarrow: InputSignal<boolean | undefined> = input<boolean>();
+public readonly isMobile: InputSignal<boolean | undefined> = input<boolean>();
 public readonly save: OutputEmitterRef<void> = output<void>();
 
 protected readonly myButton: Signal<ElementRef | undefined> = viewChild<ElementRef>('button');
 ```
 
-Декораторной формы входов, выходов и запросов к разметке в дереве нет: у неё нет типа, который
-видно в месте использования, и нет реактивности, на которую можно подписаться.
+Декораторов `@Input()`, `@Output()`, `@ViewChild()`, `@ContentChild()` и их множественных пар
+в дереве нет.
 
-## Производное значение — вычисляемое, а не эффект
+## Производное значение — `computed`, а не эффект
+
+```typescript
+protected readonly items: WritableSignal<Item[]> = signal<Item[]>([]);
+protected readonly itemCount: Signal<number> = computed((): number => this.items().length);
+protected readonly hasItems: Signal<boolean> = computed((): boolean => this.itemCount() > 0);
+```
 
 ```typescript
 ✗ effect((): void => { this.count.set(this.items().length); });
 ✓ protected readonly count: Signal<number> = computed((): number => this.items().length);
 ```
 
-Эффект, кладущий значение в реактивное поле, — это ручной пересчёт, и он рано или поздно
-отстаёт от источника. Геттера в компоненте не заводить: он пересчитывается на каждой
-перерисовке, и цена его не видна ни в одном месте кода.
+Геттера в компоненте не заводить: он пересчитывается на каждой перерисовке, и цена его не
+видна ни в одном месте кода.
 
-## Состояние службы
+## Состояние сервиса
 
 Наружу — только чтение:
 
@@ -60,7 +65,7 @@ export class DomainStateService {
 
 ## Подписка объявляется один раз
 
-Метод действия толкает значение в источник, подписка живёт при создании владельца:
+Метод действия толкает значение в источник, подписка живёт в конструкторе:
 
 ```typescript
 readonly #loadSource: Subject<void> = new Subject<void>();
@@ -69,7 +74,7 @@ readonly #destroyRef: DestroyRef = inject(DestroyRef);
 constructor() {
     this.#loadSource
         .pipe(
-            switchMap((): Observable<IResult> => this.#api.getList(this.#query())),
+            switchMap((): Observable<IPromoCode.ListResult> => this.#api.getList(this.#query())),
             takeUntilDestroyed(this.#destroyRef)
         )
         .subscribe();
@@ -80,15 +85,17 @@ protected reload(): void {
 }
 ```
 
-Оператор выбирается по тому, что делать с предыдущим запросом: список берёт последний ответ,
-кнопка не плодит дублей, независимые строки идут параллельно.
+Оператор выбирается по тому, что делать с предыдущим запросом: список берёт последний ответ
+(`switchMap`), кнопка не плодит дублей (`exhaustMap`), соседние строки идут независимо
+(`mergeMap`).
 
 ## Частые промахи
 
-- **Подписка внутри метода:** правило линтера отбивает, а вместе с ним отбивается и гонка
+- `.subscribe()` внутри метода: правило линтера отбивает, а вместе с ним отбивается и гонка
   ответов на быстрых нажатиях.
-- **Подписка без гашения:** она переживает владельца и держит уничтоженный экран в памяти.
-- **Поле-поток без суффикса источника:** поток и значение в коде становятся неотличимы.
-- **Параметры конструктора вместо функции внедрения** — везде, включая базовые классы.
-- **Эффект без снятия слежения там, где зависимость не нужна:** он просыпается на каждое чужое
-  изменение.
+- Подписка без `takeUntilDestroyed`: она переживает владельца и держит уничтоженный экран в
+  памяти.
+- Поле-поток без суффикса `Source`: поток и значение в коде становятся неотличимы.
+- `inject()` вместо параметров конструктора — везде, включая базовые классы.
+- `untracked()` там, где эффекту не нужна зависимость от сигнала: без него эффект просыпается
+  на каждое чужое изменение.

package/assets/patterns/api-layer-pair.md

@@ -2,19 +2,19 @@
 name: api-layer-pair
 kind: pattern
 rule: api-layer
-description: Паттерн правила api-layer. Брать при заведении или правке слоя обращения к серверу во фронтовом домене — готовые фасад и служба, единственный вход выборки, общий конвертер страницы, типы порядка и отбора при сущности.
+description: Паттерн правила api-layer. Брать при заведении или правке слоя api фронтового домена — готовые фасад и сервис, вход выборки, конвертер страницы, типы порядка и отбора в неймспейсе сущности. Не брать для модели и её маппера — это паттерн entity-models-new.
 ---
 
-# Фасад и служба домена
+# Фасад и сервис домена
 
 Паттерн правила `api-layer`. Что при этом должно быть верно — закон
-`{{lawsDir}}/frontend-application.md`.
+`docs/constitution/frontend-application.md`.
 
 ## Когда брать
 
-- Заводится слой обращения к серверу у нового домена.
+- Заводится слой `api` нового домена.
 - Список переводится на общую выборку.
-- Появляется новый обработчик, за которым ходит экран.
+- Появляется новая процедура, за которой ходит экран.
 
 ## Фасад
 
@@ -23,56 +23,66 @@ description: Паттерн правила api-layer. Брать при заве
 
 ```typescript
 @Injectable({ providedIn: 'root' })
-export class EntityApiFacade implements IListApiFacade<TListRequest, TListResponse, TItemResponse> {
-    readonly #client: Client<typeof DomainService> = injectClient(DomainService);
-
-    public getList(request: TListRequest): Observable<TListResponse> {
-        return from(this.#client.listItems(request));
+export class PromoCodeApiFacade implements IListApiFacade<
+    MessageInitShape<typeof ListPromoCodesRequestSchema>,
+    ListPromoCodesResponse,
+    GetPromoCodeResponse
+> {
+    readonly #client: Client<typeof PricingService> = injectConnectClient(PricingService);
+
+    public getList(request: MessageInitShape<typeof ListPromoCodesRequestSchema>): Observable<ListPromoCodesResponse> {
+        return from(this.#client.listPromoCodes(request));
     }
 }
 ```
 
 Метод, которого у домена нет, не объявляется: список читают все, правят не все.
 
-## Служба
+## Сервис
 
 Принимает доменные модели, отдаёт их же. Тип контракта до стора и шаблона не доходит:
 
 ```typescript
-export class EntityApiService implements IListApiService<IEntity.State, ESortProperty, EFilterProperty, IEntity.Draft> {
-    public getList(query: IEntity.Query): Observable<IEntity.ListResult> {
+export class PromoCodeApiService implements IListApiService<
+    IPromoCode.State,
+    EPromoCodeSortProperty,
+    EPromoCodeFilterProperty,
+    IPromoCode.Draft
+> {
+    public getList(query: IPromoCode.Query): Observable<IPromoCode.ListResult> {
         return this.#facade
             .getList({ query: this.#queryMapper.mapTo(query) })
             .pipe(
-                map((response: TListResponse): IEntity.ListResult =>
-                    convertPaginationApiModelToStateModel((item: TItem): IEntity.State => this.#mapper.mapFrom(item), response)
+                map((response: ListPromoCodesResponse): IPromoCode.ListResult =>
+                    convertPaginationApiModelToStateModel((item: PromoCodeInfo): IPromoCode.State => this.#mapper.mapFrom(item), response)
                 )
             );
     }
 }
 ```
 
-Выборка — единственный вход: объект, к которому привязан список, род ленты, состояние подписки
-— это условия отбора, и лежат они в её условиях.
+`getList` принимает выборку и больше ничего: объект, к которому привязан список, тип фида,
+состояние подписки — это условия отбора, и лежат они в `filterModel`.
 
-## Типы выборки при сущности
+## Типы выборки в неймспейсе сущности
 
 ```typescript
-export type Query = IList.Query.State<ESortProperty, EFilterProperty>;
-export type ListResult = IList.Result.State<IEntity.State, ESortProperty, EFilterProperty>;
+export type Query = IList.Query.State<EPromoCodeSortProperty, EPromoCodeFilterProperty>;
+export type ListResult = IList.Result.State<IPromoCode.State, EPromoCodeSortProperty, EPromoCodeFilterProperty>;
 ```
 
-Перечисления порядка и отбора объявляются рядом с сущностью и повторяют набор имён, по которым
-сортирует и отбирает сервер именно этого домена.
+Перечисления `EPromoCodeSortProperty` и `EPromoCodeFilterProperty` объявляются в модели рядом с
+сущностью и повторяют набор имён, по которым сортирует и отбирает сервер этого домена.
 
 ## Частые промахи
 
-- **Промежуточный объект между ответом и моделью:** ответ ложится в конвертер целиком.
-- **Выборка из своего запроса вместо применённой из ответа:** умолчание сервера и отброшенное
-  им условие экран иначе не увидит.
-- **Второй вход рядом с выборкой:** отбор, живущий отдельно, не виден ни стору, ни адресу.
-- **Голая строка в поле порядка:** имя, по которому сервер не сортирует, компилируется и падает
+- Промежуточный объект между ответом и моделью: ответ ложится в конвертер целиком.
+- Выборка из своего запроса вместо применённой из ответа: умолчание сервера и отброшенное им
+  условие экран иначе не увидит.
+- Второй вход рядом с выборкой (`propertyId`, `feedType`): отбор, живущий отдельно, не виден ни
+  стору, ни адресу.
+- Голая `string` в поле порядка: имя, по которому сервер не сортирует, компилируется и падает
   запросом.
-- **Один класс на две сущности:** подмена источника одной потянет за собой правку другой.
-- **Служба на обещаниях в новом сторе:** основа списочного стора работает потоками.
-- **Своя копия общих переводчиков страницы, порядка и отбора** — её ловит проверка повторов.
+- Один класс на две сущности: подмена источника одной потянет за собой правку другой.
+- Промисный сервис в новом сторе: основа списочного стора работает потоками.
+- Своя копия общих мапперов страницы, порядка и отбора — её ловит `npm run check:dupes`.

package/assets/patterns/browser-verification-measure.md

@@ -2,13 +2,13 @@
 name: browser-verification-measure
 kind: pattern
 rule: browser-verification
-description: Паттерн правила browser-verification. Брать, когда вывод о вёрстке надо подкрепить числом — готовые замеры, разбивка вычисленного значения по всем узлам, узкий экран вложенной рамкой, ловушки инструмента снимка экрана. Не брать для подъёма стенда — это паттерн browser-verification-stand.
+description: Паттерн правила browser-verification. Брать, когда вывод о вёрстке надо подкрепить числом — готовые замеры, разбивка вычисленного значения по всем узлам, узкий экран через iframe, ловушки инструмента computer. Не брать для подъёма стенда — это паттерн browser-verification-stand.
 ---
 
 # Замер вместо взгляда
 
 Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
-`{{lawsDir}}/verifiability.md`.
+`docs/constitution/verifiability.md`.
 
 ## Когда брать
 
@@ -18,21 +18,23 @@ description: Паттерн правила browser-verification. Брать, к
 
 ## Вывод подкрепляется числом
 
-Вычисленный стиль, прямоугольник элемента, контраст, совпадение центров, попадание в видимую
-область. «Выглядит нормально» результатом проверки не является.
+`getComputedStyle`, `getBoundingClientRect`, контраст, совпадение центров, попадание во
+вьюпорт. «Выглядит нормально» результатом проверки не является.
 
-Замер отвечает только на тот вопрос, который задали. Совпадение перечисленных свойств ничего не
-говорит о правиле, которого в списке замера нет. Если исходники образца доступны, расхождение
-ищется чтением, а замер остаётся проверкой результата.
+Замер отвечает только на тот вопрос, который задали. Совпадение перечисленных свойств ничего
+не говорит о правиле, которого в списке замера нет: строки попапа профиля сошлись с образцом
+по отступам, кеглю и скруглению, а фон на наведении образец в этом месте не красит вовсе —
+полноширинная подсветка держалась два круга при верных числах. Если исходники образца
+доступны, расхождение ищется чтением, а замер остаётся проверкой результата.
 
 Вид элемента, которого сегодня не видно ни на одном экране, замером не подтверждается, и
 правило о нём остаётся гипотезой.
 
 ## Значение, которого в коде нет
 
-Гарнитуру, межстрочный интервал, цвет и оформление элементам формы задаёт браузер, и в дереве
-этих значений нет. Поиск по коду на такой дефект отвечает «чисто», линтер и сборка молчат.
-Ищется разбивкой вычисленного значения по всем узлам страницы, а не замером у пары элементов:
+Гарнитуру, `line-height`, цвет и `appearance` элементам формы задаёт браузер, и в дереве этих
+значений нет. Поиск по коду на такой дефект отвечает «чисто», линт и сборка молчат. Ищется
+разбивкой вычисленного значения по всем узлам страницы, а не замером у пары элементов:
 
 ```javascript
 [...document.querySelectorAll('*')].reduce((acc, el) => {
@@ -42,42 +44,43 @@ description: Паттерн правила browser-verification. Брать, к
 }, {});
 ```
 
-Счёт годится любому наследуемому свойству: смотрится не одно значение, а число узлов с
-неожиданным. Так находятся десятки элементов, набранных не той гарнитурой, — по одному их не
-заметил бы никто.
+Так на дашборде админки нашёлся 91 контрол из 106, набранный не той гарнитурой, и 13 из 87 на
+главной сайта. Счёт годится любому наследуемому свойству: смотрится не одно значение, а число
+узлов с неожиданным.
 
 ## Узкий экран
 
-Изменение размера окна не работает, когда браузер в полноэкранном режиме: инструмент рапортует
-успех, ширина не меняется, медиазапросы остаются широкими. Узкие ширины проверяются во
-вложенной рамке нужной ширины — внутри неё запрос ширины считается от рамки, и рамка своей
-толщиной уменьшает внутреннюю ширину.
+`resize_window` не работает, когда Chrome в полноэкранном режиме: инструмент рапортует успех,
+`innerWidth` не меняется, медиазапросы остаются десктопными. Узкие ширины проверять во
+вложенном iframe нужной ширины — внутри него `matchMedia` считается от рамки; при
+`width: 375px` и `border: 2px` внутренний `innerWidth` равен 371.
 
-Правка числа элементов в контейнере — это правка раскладки: она проверяется на узкой ширине, а
-не только кодами ответа.
+Правка числа элементов в контейнере — это правка раскладки: она проверяется при 375, а не
+только кодами ответа.
 
-## Ловушки инструмента снимка экрана
+## Ловушки инструмента `computer`
 
-- **Координаты нажатия — координаты снимка, а не страницы.** При широком окне снимок приходит
-  уже, и нажатие по «увиденной» координате уходит мимо, давая ложный сигнал: пересчитывать по
-  фактическому масштабу либо целиться поиском элемента.
-- **Область приближения должна целиком лежать внутри видимой области.**
-- **Между нажатиями обязательно ожидание:** цикл «нажал — прочитал разметку» без него читает
-  состояние до перерисовки и возвращает устаревшие значения.
-- **Выбор браузера протухает.** На длинной проверке это срабатывает посреди работы — не сбой
-  стенда, а повод повторить вызов и продолжить.
+- Координаты клика — координаты **скриншота**, а не CSS-пиксели: при вьюпорте 2560 скриншот
+  приходит шириной 1568, и клик по «увиденной» координате уходит мимо, давая ложный сигнал.
+  Пересчитывать по фактическому масштабу либо целиться через `find`.
+- Область `zoom` должна целиком лежать внутри вьюпорта.
+- Между кликами обязателен `await`: синхронный цикл «кликнул — прочитал DOM» читает состояние
+  до перерисовки и возвращает устаревшие значения.
+- `select_browser` протухает через 300 секунд. На длинной проверке это срабатывает посреди
+  работы — это не сбой стенда, повторить вызов и продолжить. Закреплённый профиль — тот, что записан в дереве, идентификатор `062b17db-ae82-4264-927c-e9904d0dd5be`.
 
-## Поведение маршрутизации воспроизводится нажатиями
+## Поведение роутера воспроизводится нажатиями
 
-Подстановка адреса, программный переход и заход по прямой ссылке поднимают приложение заново, и
-накопленного состояния — открытой панели, стража прошлого экрана — у него нет. Чистый проход по
-адресам читается как «дефект не подтверждается».
+Подстановка адреса, `history.pushState` с `popstate` и заход по прямой ссылке поднимают
+приложение заново, и накопленного состояния — открытого аутлета, гарда прошлой панели — у него
+нет. Чистый проход по адресам читается как «дефект не подтверждается»: панель ленты событий
+застревала на первом же нажатии из меню и трижды прошла проверку адресами.
 
 ## Частые промахи
 
-- **Комментарий в конфиге — гипотеза наравне с прочими.** Утверждение о поведении кэша
-  переживает несколько кругов разбора кода и опровергается одним запросом.
-- **Вывод «дефекта нет, это кэш» закрывает разбор**, поэтому принимается только после проверки
-  на чистой сборке.
-- **Дефект в клиентском куске от компиляции до правки выглядит как дефект кода** — признак
-  сборки для разработки — имена файлов без хеша.
+- Комментарий в конфиге — гипотеза наравне с прочими. Утверждение о вытеснении записи кэша
+  продержалось три круга состязательного разбора кода и было опровергнуто одним `curl`.
+- Вывод «дефекта нет, это кэш» закрывает разбор, поэтому принимается только после проверки на
+  чистой сборке.
+- Дефект в клиентском чанке от компиляции до правки выглядит как дефект кода: признак
+  дев-сборки — имена бандла без хеша.

package/assets/patterns/browser-verification-stand.md

@@ -2,78 +2,142 @@
 name: browser-verification-stand
 kind: pattern
 rule: browser-verification
-description: Паттерн правила browser-verification. Брать, когда нужен честный стенд — прод-сборка, стенд под настоящим прокси, вход в приложение, разбор того, что висит на порту, стенд серверной стороны с переменными окружения. Не брать для замеров вёрстки — это паттерн browser-verification-measure.
+description: Паттерн правила browser-verification. Брать, когда нужен честный стенд — прод-сборка сайта, стенд админки, стенд под настоящим nginx, вход в админку, разбор того, что висит на порту. Не брать для замеров вёрстки — это паттерн browser-verification-measure.
 ---
 
 # Честный стенд
 
 Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
-`{{lawsDir}}/verifiability.md`.
+`docs/constitution/verifiability.md`.
 
 ## Когда брать
 
-- Проверяется то, чего на сервере разработки не видно: разметка от сервера, локали, кэш,
-  перенаправления, заголовки, размер сборки.
+- Проверяется то, чего на дев-сервере не видно: разметка от сервера, локали, кэш,
+  перенаправления, заголовки, размер бандла.
 - Порт отвечает не тем, чего ждали.
-- Нужен вход в приложение.
+- Нужен вход в админку.
 
 ## Сначала — что отвечает на порту
 
 До первого запроса, а не после непонятного ответа:
 
 ```bash
-lsof -nP -iTCP:<порт> -sTCP:LISTEN
+lsof -nP -iTCP:{{apiPort}} -sTCP:LISTEN
 ```
 
-На порту регулярно висит собранный артефакт из прошлой сессии: он отвечает успехом на старом
-коде, а заведённого в ветке обработчика у него нет вовсе. Таких процессов бывает несколько, и
-снимать надо все — по идентификатору из вывода, каждый: завершение по шаблону команды не
-попадает ни в один.
+На {{apiPort}} регулярно висит собранный артефакт из прошлой сессии
+(`node -r dotenv/config dist/apps/api/main.js`): он отвечает 200 старым кодом, а процедуры,
+заведённой в ветке, у него нет вовсе. Таких процессов бывает несколько, и снимать надо все —
+по PID из `lsof`, каждый: `pkill` по шаблону `nx serve api` не попадает ни в один.
 
-## Прод-сборка
+## Прод-сборка сайта
 
-Собранный сервер поднимается прямо, а не через сервер разработки: гард ловит запуск сервера
-разработки, пакетные раннеры и статические серверы, а запуск собранного сервера пропускает.
+```bash
+npx nx build site
+PORT={{prodSitePort}} node dist/apps/site/server/server.mjs
+```
+
+Это не дев-сервер: гард ловит `nx|ng serve`, пакетные раннеры и статические серверы, а запуск
+собранного сервера пропускает.
 
-Приложению, отдающему статику, нужен явный базовый адрес — без него стенд отдаёт пустую
-страницу без единой ошибки в консоли. Стенду, на котором нужны отладочные инструменты каркаса,
-нужна сборка для разработки: прод-сборка их не публикует. Выводы о размере сборки и минификации
-на такой сборке делать нельзя.
+## Стенд админки
+
+```bash
+npx nx build admin --base-href=/
+```
 
-## Вход в приложение
+Без `--base-href` стенд отдаёт пустую страницу без ошибок в консоли. Стенду, на котором нужен
+Angular DevTools, нужна ещё и dev-конфигурация (`--configuration=development`): прод-сборка не
+публикует `window.ng`. Выводы о размере бандла и минификации на такой сборке делать нельзя.
 
-Сессия кладётся в хранилище браузера ровно в той форме, в какой её читает приложение: значение,
-записанное иначе, приложение молча не увидит. Токен не подписывается руками, а берётся у живого
-сервера входом.
+Сессия кладётся в `localStorage['vm.admin.token']` **строкой JSON** (`JSON.stringify(token)`),
+иначе приложение её не прочитает. Токен не подписывается руками, а берётся у живого API:
+`POST /<область>.v1.AuthService/Login`. Команду с паролем классификатор блокирует — обходить не
+надо, спрашивать разрешение у владельца.
 
-Взять уже открытую сессию нельзя: чтение хранилища чужого профиля блокируется. Оба пути к
-своему стенду упираются в пароль, поэтому остаётся третий — смотреть там, где вход уже сделан.
-Свой стенд нужен, только когда проверяют прод-сборку, базовый адрес или конфиг прокси; чтобы
-просто посмотреть экраны, он не нужен.
+Взять уже открытую сессию нельзя: чтение `localStorage['vm.admin.token']` из браузера
+блокируется. Оба пути к своему стенду упираются в пароль, поэтому остаётся третий — смотреть
+на админке владельца, где вход уже сделан. Свой стенд нужен, только когда проверяют
+прод-сборку, `--base-href` или конфиг nginx; чтобы просто посмотреть экраны, он не нужен.
 
-## Стенд серверной стороны
+## Стенд API
 
-Собранный артефакт поднимается на свободном порту, а не на рабочем: на рабочем отвечает сервер
+Собранный артефакт поднимается на свободном порту, а не на {{apiPort}}: на {{apiPort}} отвечает API
 владельца, и окружение у него не то, которое проверяется.
 
-Переменные окружения задаются в самой команде, по одной на проверяемый случай. Отказ на старте
-— такой же результат проверки, как успешный ответ: приложение, упавшее при сборке зависимостей,
-порт не слушает вовсе, и это видно по списку слушателей, а не по тексту в консоли.
+```bash
+npx nx build api
+env -u JWT_SECRET NODE_ENV=production API_PORT={{prodApiPort}} DATABASE_URL=… node dist/apps/api/main.js
+```
+
+Переменные окружения задаются в самой команде, по одной на проверяемый случай. Отказ на
+старте — такой же результат проверки, как ответ 200: приложение, упавшее в фабрике
+провайдера, порт не слушает вовсе, и это видно по `lsof`, а не по тексту в консоли.
 
-Обработчик зовётся полным именем, как его объявляет контракт. Токен подписывается руками только
-там, где проверяется сама подпись; во всех остальных случаях он берётся у живого сервера входом
-— рукописный скрывает расхождение состава притязаний.
+Процедура зовётся полным именем, как её объявляет контракт:
+
+```bash
+curl -sS -X POST http://localhost:{{prodApiPort}}/<область>.v1.AuthService/GetMe \
+    -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" -d '{}'
+```
 
-## Стенд под настоящим прокси
+Токен подписывается руками только там, где проверяется сама подпись: доказать, что отладочный
+ключ принимается, другого пути не имеет. Во всех остальных случаях токен берётся у живого API
+входом — рукописный скрывает расхождение состава притязаний.
+
+## Стенд под настоящим nginx
+
+Кэш, перенаправления и заголовки живут в `deploy/nginx.conf`, а не в приложении. Любой вывод
+про `301`, `Cache-Control` и `X-Cache-Status` делается только здесь:
+
+```bash
+docker run -d --name <префикс>-stand-nginx \
+  --add-host api:host-gateway --add-host ssr:host-gateway \
+  -p {{dockerSitePort}}:80 -p {{dockerAdminPort}}:8081 \
+  -v "$PWD/deploy/nginx/main.conf:/etc/nginx/nginx.conf:ro" \
+  -v "$PWD/deploy:/etc/nginx/conf.d:ro" \
+  -v "$PWD/dist/apps/admin/browser:/usr/share/nginx/html/admin:ro" \
+  nginx:1.27-alpine
+```
+
+- Конфиг монтируется **каталогом**, а не одиночным файлом: редактор пересоздаёт файл,
+  контейнеру остаётся обрезанная копия, и `nginx -t` внутри падает на «unexpected end of file»
+  при целом файле снаружи. Лечится пересозданием контейнера, а не правкой конфига.
+- Главный конфиг подставляется отдельной строкой: он лежит в `deploy/nginx/`, а не рядом с
+  `nginx.conf`, — файл с расширением `.conf` в смонтированном каталоге попал бы в `include`
+  и уронил бы nginx на директиве `user`. Без него стенд поднимается на конфиге образа, и
+  предел соединений на воркер там свой.
+- Сервер отдачи страниц отвечает `400` на чужой `Host`: все запросы идут с
+  `-H "Host: localhost"`.
+- Переменные окружения стенда обязаны смотреть на процессы стенда. `CACHE_REFRESH_URL`,
+  направленный на {{sitePort}}, сбрасывает кэш мимо того процесса, который держит справочник
+  перенаправлений в памяти, — исправный механизм при этом выглядит сломанным.
+
+## Дерево для сравнения
+
+Сказать «это сломала правка» можно, только если видно, что до правки было иначе. Проверяют это
+вторым деревом, а не по памяти:
+
+```bash
+git worktree add ../<префикс>-base <коммит>   # ветка задачи не трогается
+pnpm install --frozen-lockfile         # из ../<префикс>-base: node_modules у него свои
+```
 
-Кэш, перенаправления и заголовки живут в конфиге прокси, а не в приложении, и любой вывод о них
-с голого сервера отдачи страниц неверен. Устройство такого стенда — паттерн `testing-e2e`.
+- Для сравнения берут не главную ветку, а последний коммит, на котором дерево собирается:
+  главная бывает сломана, и тогда «до» и «после» различаются не из-за правки. Собирается ли
+  коммит — проверяют сборкой, а не тем, что он в главной ветке.
+- Стенд второго дерева поднимают на своих портах: {{sitePort}}, {{adminPort}} и {{apiPort}} заняты владельцем, а {{ssrPort}}
+  занимать нельзя — стенд разработчика ходит по имени `ssr:{{ssrPort}}`.
+- Оба стенда держат поднятыми одновременно: если сравнивать по памяти между двумя запусками,
+  заметишь только то, что успел запомнить.
 
 ## Частые промахи
 
-- **Порт занят чужой сборкой, а ответ читается как дефект ветки.** Сначала список слушателей,
-  потом запрос.
-- **Стенд без явного базового адреса отдаёт пустую страницу** и ни одной ошибки при этом не
-  печатает.
-- **Токен, подписанный руками, скрывает расхождение состава притязаний** — вход берётся у
-  живого сервера.
+- Свой дев-сервер не поднимать: сайт на {{sitePort}}, админка на {{adminPort}}, API на {{apiPort}} уже подняты
+  владельцем, и второй экземпляр отбивается гардом.
+- **Общая сборка глушит все три дев-сервера владельца, а не только API.** После
+  `nx run-many -t build` ложатся и сайт на {{sitePort}}, и админка на {{adminPort}}. Собирать надо то, что
+  проверяешь (`npx nx build site`), а не всё дерево. Если серверы легли, поднять их обратно
+  агент не может — мешает гард, поэтому владельцу говорят об этом сразу, а не в конце сессии.
+- Порт {{ssrPort}} занимать осторожно: стенд разработчика на {{sitePort}} ходит по тому же имени `ssr:{{ssrPort}}`
+  через `host-gateway`, и пока на нём висит чужой процесс, стенд отдаёт чужую сборку.