@coraltravelcenter/b2c-landing-builder 2.14.2 → 3.0.0

package/README.md

@@ -1,224 +1,174 @@
 # @coraltravelcenter/b2c-landing-builder
 
-Глобальный CLI для разработки B2C-лендингов через Tampermonkey и сборки
-CMS-готовых HTML-файлов.
+CLI для разработки B2C-лендингов, локального предпросмотра через Tampermonkey,
+сборки CMS-готовых HTML-блоков и управляемой публикации ассетов и виджетов в
+Backoffice.
 
-## Установка
+Builder устанавливается глобально и запускается из каталога проекта. Исходники
+builder, `vite.config.js` и собственные build-скрипты проекту не нужны.
 
-Требуется Node.js 20.19 или новее.
+## Требования и установка
+
+- Node.js 20.19 или новее;
+- Tampermonkey для локального предпросмотра;
+- офисная сеть или VPN для работы с Backoffice.
 
 ```bash
 npm install --global @coraltravelcenter/b2c-landing-builder
+b2c-landing-vite --help
 ```
 
-Builder устанавливается один раз и не копируется в проекты лендингов.
-
-## Команды
-
-Команды выполняются из корня проекта:
+## Создание проекта
 
 ```bash
-b2c-landing-vite check
+npm create @coraltravelcenter/b2c-landing-vite
+cd <project-directory>
+npm install
+b2c-landing-vite check --strict
 b2c-landing-vite dev
-b2c-landing-vite build
-b2c-landing-vite deploy
-b2c-landing-vite deploy --section hero
-b2c-landing-vite deploy assets
-b2c-landing-vite block:add hero
-b2c-landing-vite block:rename hero main-hero
-b2c-landing-vite update
 ```
 
-- `check` проверяет конфигурацию, `order.json` и контракт JS-блоков.
-- `dev` запускает Vite и отдельный userscript с названием проекта для
-  Tampermonkey.
-- `build` создаёт CMS-файлы в `@CMS/` и переписывает пути ассетов на CDN.
-- `deploy` собирает проект, синхронизирует ассеты с CDN и после успешной
-  синхронизации разворачивает CMS-виджеты.
-- `deploy --section <key>` разворачивает только выбранную CMS-секцию, не изменяя
-  и не удаляя соседние секции.
-- `deploy assets` собирает проект и синхронизирует ассеты с B2C CDN.
-- При первом deploy builder запрашивает backoffice-логин и скрытый пароль через
-  ADFS. На диск сохраняется только токен. Для CI можно передать
-  `B2C_BACKOFFICE_TOKEN`.
-- Backoffice-запросы ограничены 30 секундами. Безопасные GET-запросы повторяются
-  до двух раз при сетевом сбое, timeout, HTTP 429, 502, 503 или 504. Изменяющие
-  CMS запросы автоматически не повторяются, чтобы не создать дубликаты.
-- После успешного deploy builder сохраняет снимок секций в `.b2c/deploy/` как
-  достоверный `base`. Следующий deploy структурно сравнивает секции `local`,
-  актуальный `remote` и `base`. Изменения разных секций объединяются; изменение
-  одной секции с обеих сторон считается конфликтом.
-- Если `base` ещё отсутствует, отличие local от remote считается потенциальным
-  конфликтом. Обычный deploy не выполняет silent overwrite и предлагает явно
-  сохранить CMS-версию, применить local или отменить операцию.
-- Стабильные `pageId`, `layoutAreaId` и позиция сохраняются отдельно в
-  `.b2c/deploy/<site>--<folder>.binding.json`. Этот файл можно хранить в Git,
-  чтобы команда находила ту же CMS-страницу после нового клонирования проекта.
-- Перед deploy builder получает список версий сохранённой страницы. Published
-  выбирается по умолчанию; из Published или Unpublished создаётся checkout,
-  существующий Checkout обновляется напрямую. Потерянную привязку можно
-  восстановить интерактивным выбором существующей страницы.
-- Одновременные deploy одного проекта на компьютере блокируются lock-файлом в
-  `.b2c/deploy/`; аварийно оставленный lock автоматически признаётся устаревшим.
-- Непосредственно перед первой записью CMS-состояние читается повторно. Если оно
-  изменилось во время проверки/выбора стратегии, deploy останавливается.
-- `block:add` создаёт файлы в выбранных форматах разметки и стилей.
-- `block:rename` атомарно переименовывает все файлы блока и обновляет порядок.
-- `update` проверяет npm registry и показывает команду ручного обновления.
-
-После успешного выполнения рабочих команд builder коротко и независимо
-проверяет в npm registry версии самого builder и шаблона проекта. Для проекта
-без `template.version` шаблон помечается как `legacy`. Ошибки сети не влияют на
-работу CLI; ничего не обновляется автоматически:
+Генератор: [CoralTravelCenter/create-b2c-landing-vite](https://github.com/CoralTravelCenter/create-b2c-landing-vite).
 
-```bash
-b2c-landing-vite update
-# Update manually: npm install --global @coraltravelcenter/b2c-landing-builder@latest
-# Update project template: npx @coraltravelcenter/create-b2c-landing-vite@latest migrate
-```
+## Основной рабочий процесс
 
-## Создание проекта
+1. Добавьте или измените блоки в `src/`.
+2. Запустите `b2c-landing-vite check --strict`.
+3. Проверьте результат через `b2c-landing-vite dev` и Tampermonkey.
+4. Перед публикацией выполните `b2c-landing-vite deploy --dry-run`.
+5. Примените проверенный план командой `b2c-landing-vite deploy`.
 
-Новые проекты создаются отдельным пакетом:
+Для предварительной загрузки ассетов без изменения CMS используйте
+`b2c-landing-vite deploy assets`.
 
-```bash
-npm create @coraltravelcenter/b2c-landing-vite
+### Терминальный интерфейс
+
+Каждая команда показывает единый структурированный сценарий: название команды и
+проекта, текущие стадии, важные параметры, подтверждения и итог. Терминальные
+подписи остаются на английском и одинаково используются в `check`, `dev`,
+`build`, block-командах и всех вариантах deploy.
+
+Полный deploy открывает одну terminal-сессию. Вложенные build, CDN и CMS-этапы
+отображаются внутри неё, без повторных заголовков и ложных промежуточных
+`complete`. Ошибка сохраняет исходную диагностику и ненулевой exit code.
+
+В интерактивном терминале прогресс может отображаться spinner-анимацией. При
+перенаправлении вывода содержательные подписи, пути и URL остаются текстовыми.
+
+## Структура проекта
+
+```text
+src/
+  order.json
+  markup/
+    welcome.html | welcome.pug
+  styles/
+    welcome.css | welcome.scss | welcome.less
+  scripts/
+    welcome.js | welcome.ts
+    utils/                 # общие JS/TS-утилиты
+  components/              # компоненты проекта для Vue-стека
+public/                     # исходные статические файлы
+pug.rc                      # настройки Pug, если выбран Pug
+landing.config.mjs
+package.json
 ```
 
-Репозиторий генератора:
-[CoralTravelCenter/create-b2c-landing-vite](https://github.com/CoralTravelCenter/create-b2c-landing-vite).
+Каталог `@CMS/` создаётся во время сборки. Это производный артефакт: его не нужно
+редактировать вручную или хранить в Git.
 
 ## Конфигурация
 
-В корне каждого проекта находится `landing.config.mjs`:
+Проект настраивается в `landing.config.mjs`:
 
 ```js
 export default {
   schemaVersion: 2,
-  builder: {
-    minVersion: "2.10.0",
-  },
-  template: {
-    version: "2.13.0",
-  },
-  project: {
-    name: "uae-promo",
-  },
-  site: {
-    preset: "coral",
-  },
+  builder: {minVersion: "2.10.0"},
+  template: {version: "2.13.0"},
+  project: {name: "uae-promo"},
+  site: {preset: "coral"},
   stack: {
     script: "vue",
     markup: "pug",
     styles: "less",
   },
-  blocks: {
-    static: ["html-only"],
-  },
+  blocks: {static: ["html-only"]},
 };
 ```
 
-`template.version` записывается генератором и показывает, какой версией шаблона
-создан проект. Для старых проектов поле необязательно; его отсутствие позволяет
-builder распознать legacy-шаблон и предложить миграцию в будущих версиях.
-
-Имя проекта должно соответствовать `^[a-z0-9][a-z0-9-]*$`.
+### Версии
 
-Поддерживаются:
+- `schemaVersion` — версия формата конфигурации; поддерживаются `1` и `2`.
+- Для схемы `2` обязателен `builder.minVersion`. Слишком старая версия builder
+  блокирует выполнение команд.
+- `template.version` записывает генератор. В legacy-проектах поле может
+  отсутствовать; проверка обновлений тогда предложит миграцию шаблона.
 
-- JavaScript: `js`, `ts`, `vue`, `vue-ts` (`vanilla` поддерживается для старых проектов);
-- разметка: `html`, `pug`;
-- стили: `css`, `scss`, `less`;
-- сайты: `coral`, `sunmar`.
+### Проект, сайт и стек
 
-Зависимости выбранного стека устанавливаются локально в проект: `typescript`
-для TS, `vue` и `@vitejs/plugin-vue` для Vue, `pug` для Pug, `less` для Less и
-`sass` для SCSS.
-Builder загружает Vue-плагин из проекта, поэтому Vue-зависимости не
-устанавливаются вместе с глобальным builder.
+- `project.name` должен соответствовать `^[a-z0-9][a-z0-9-]*$`.
+- `site.preset` принимает `coral` или `sunmar` и определяет домен и CDN.
 
-`blocks.static` явно перечисляет блоки без JavaScript initializer. Команда
-`b2c-landing-vite check --strict` требует initializer или такую декларацию.
-HTML-разметка поддерживает вложенные `<include src="./partial.html"></include>`.
+| Поле | Поддерживаемые значения |
+| --- | --- |
+| `stack.script` | `js`, `ts`, `vue`, `vue-ts`; `vanilla` — legacy-алиас |
+| `stack.markup` | `html`, `pug` |
+| `stack.styles` | `css`, `scss`, `less` |
 
-При первом запуске dev-сервер сохраняет выбранный свободный порт в
-`.b2c/dev-port`; следующие запуски используют его строго. Новый порт можно
-закрепить командой `B2C_PORT=5175 npm run dev`.
+Зависимости стека устанавливаются локально в проект: `typescript` для TS,
+`vue` и `@vitejs/plugin-vue` для Vue, `pug` для Pug, `sass` для SCSS и `less`
+для Less. Глобальный builder не заменяет эти зависимости.
 
-Перед подготовкой deploy-артефактов builder рекурсивно проверяет `public/`.
-Изображения JPG, JPEG и PNG конвертируются в WebP с качеством 80, а ссылки в
-CMS-файлах автоматически переключаются на новые имена. Исходные файлы в
-`public/` не изменяются. Если WebP с таким именем уже существует, используется
-он. SVG, GIF, шрифты и остальные файлы копируются без преобразования.
+### Статические блоки
 
-Monkey URL, контейнер и CDN prefix не задаются вручную:
+`blocks.static` перечисляет блоки без JavaScript/TypeScript initializer.
+`check --strict` требует, чтобы каждый блок либо имел initializer, либо был явно
+объявлен статическим. Статический блок не может одновременно иметь script entry.
 
-- URL: `https://<домен-пресета>/monkey/*`;
-- контейнер: `#monkey-app`;
-- CDN prefix: `landing-pages/<project.name>`.
+## Блоки и порядок
 
-Dev-сервер начинает с `127.0.0.1:5173` и автоматически выбирает следующий
-свободный порт, поэтому несколько проектов можно запускать одновременно. Если
-задан `B2C_PORT`, порт считается обязательным и занятое значение завершает
-команду ошибкой.
+`src/order.json` — единственный источник порядка блоков и CDN-папки:
 
-После запуска dev-сервера builder выводит рядом с локальным адресом Target URL
-и открывает его отдельной вкладкой: `https://www.coral.ru/monkey/` или
-`https://www.sunmar.ru/monkey/`. Существующая вкладка установки Tampermonkey
-userscript открывается как раньше. `B2C_NO_OPEN=1` отключает автоматическое
-открытие обеих вкладок, но Target URL остаётся в терминале.
-
-Userscript ограничен доменом выбранного бренда и дополнительно проверяет hostname
-перед монтированием. Namespace также содержит бренд, поэтому Coral и Sunmar не
-конфликтуют даже при одинаковом названии проекта.
+```json
+{
+  "folder": "uae-promo",
+  "blocks": ["hero", "welcome"]
+}
+```
 
-Для Coral и Sunmar настроены отдельные production CDN. Команда `build`
-автоматически выбирает CDN по `site.preset`.
+- `folder` должен соответствовать `^[a-z0-9][a-z0-9-]*$`;
+- CDN prefix — `<assetsBase>/landing-pages/<folder>/`;
+- ключи блоков должны быть уникальными;
+- каждому ключу нужны разметка и стили выбранных форматов.
 
-## Структура проекта
+Создание и переименование:
 
-```text
-src/
-  order.json
-  markup/
-    welcome.html | welcome.pug
-  styles/
-    welcome.css | welcome.scss | welcome.less
-  scripts/
-    welcome.js | welcome.ts
-    utils/          # общие JavaScript-утилиты проекта
-  components/       # только для Vue
-public/
-pug.rc               # только для Pug
-landing.config.mjs
-package.json
+```bash
+b2c-landing-vite block:add hero
+b2c-landing-vite block:rename hero main-hero
 ```
 
-В проекте не нужны `vite.config.js`, исходники builder или локальные build-скрипты.
+`block:add` создаёт файлы выбранного стека и добавляет ключ в конец order.
+`block:rename` сначала проверяет все пути, затем переименовывает имеющиеся
+варианты разметки, стилей и скрипта и обновляет order. Конфликт целевого файла
+останавливает команду до частичных изменений.
 
-## Порядок блоков
+### HTML include
 
-`src/order.json` является единственным источником порядка:
+HTML поддерживает относительные вложенные include:
 
-```json
-{
-  "folder": "uae-promo",
-  "blocks": ["hero", "welcome"]
-}
+```html
+<include src="./partials/card.html"></include>
 ```
 
-`folder` задаёт единственную папку проекта на CDN. Она должна быть безопасным
-именем без вложенных путей. Итоговый префикс ассетов:
-`<assetsBase>/landing-pages/<folder>/`.
-
-Для каждого ключа обязательны разметка и стиль с тем же именем. JS/TS-файл
-необязателен. Форматы определяются `landing.config.mjs`; отсутствие обязательного
-файла блокирует `check`, `dev` и `build` с указанием ожидаемого пути.
+Путь разрешается относительно исходного файла. Отсутствующий файл или
+рекурсивная цепочка блокируют проверку и сборку.
 
 ## Контракт JavaScript и TypeScript
 
-Если у блока есть `src/scripts/<key>.js` или `src/scripts/<key>.ts`, файл обязан
-экспортировать функцию инициализации по умолчанию:
+Script entry `src/scripts/<key>.js` или `.ts` экспортирует initializer по
+умолчанию:
 
 ```js
 export default function hero() {
@@ -229,79 +179,313 @@ export default function hero() {
 }
 ```
 
-Builder вставляет разметку, затем вызывает функцию без аргументов. Скрипт блока
-сам находит свою разметку в `document`. Этот контракт одинаков для dev и CMS
-build; дополнительные контейнеры builder не создаёт. Блок без JS допустим.
+Builder вставляет разметку, затем вызывает функцию без аргументов. Функция сама
+находит блок в `document`. Дополнительные контейнеры builder не создаёт.
+
+Расширение entry определяется `stack.script`: например, при `ts` файл `hero.js`
+считается конфликтующим, а не альтернативным entry.
+
+## Проверка проекта
+
+```bash
+b2c-landing-vite check
+b2c-landing-vite check --strict
+```
+
+Проверяются конфигурация и версии, локальные зависимости стека, `src/order.json`,
+файлы блоков, HTML include, расширение script entry и default initializer.
+Strict-режим дополнительно проверяет контракт статических блоков. Команда не
+собирает проект и не обращается к CDN или CMS.
 
-## Изображения
+## Локальная разработка
 
-Изображения хранятся в `public/` и используются от корня:
+```bash
+b2c-landing-vite dev
+```
+
+Builder запускает Vite на `127.0.0.1`, создаёт Tampermonkey userscript с
+названием проекта и открывает его установку и Target URL:
+
+- `https://www.coral.ru/monkey/`;
+- `https://www.sunmar.ru/monkey/`.
+
+Userscript ограничен доменом выбранного бренда, проверяет hostname и использует
+namespace с site preset. Проекты Coral и Sunmar с одинаковым названием поэтому
+не конфликтуют.
+
+На Target URL userscript ждёт контейнер `#monkey-app`, последовательно вставляет
+в него блоки из `src/order.json`, а затем вызывает их initializer. Повторное
+монтирование в тот же контейнер блокируется.
+
+### Порт и вкладки
+
+Первый запуск начинается с `5173` и при необходимости выбирает следующий
+свободный порт. Он сохраняется в `.b2c/dev-port`; следующие запуски используют
+его строго.
+
+```bash
+B2C_PORT=5175 b2c-landing-vite dev
+B2C_NO_OPEN=1 b2c-landing-vite dev
+```
+
+`B2C_PORT` назначает обязательный порт от `1` до `65535`.
+`B2C_NO_OPEN=1` отключает автоматическое открытие вкладок.
+
+### Обновление страницы
+
+- Стили и Vue-компоненты используют штатный HMR Vite.
+- Разметка, script entry, `src/order.json` и `pug.rc` вызывают полную перезагрузку.
+- Добавление и удаление разметки или script entry также перезагружает страницу.
+
+Root-relative URL из `public/` в dev направляются на origin текущего Vite-сервера.
+
+## Production build
+
+```bash
+b2c-landing-vite build
+```
+
+Сборка:
+
+1. Проверяет проект и зависимости стека.
+2. Создаёт отдельный `@CMS/<key>.html` для каждого блока.
+3. Переписывает root-relative media URL на production CDN site preset.
+4. Готовит копию ассетов в `@CMS/assets/`.
+5. Конвертирует JPG, JPEG и PNG в WebP с качеством `80`.
+6. Обновляет CMS HTML после конвертации.
+7. Создаёт `@CMS/manifest.json` с путями, размерами и SHA-256.
+
+Исходники в `public/` не меняются. Существующий WebP с нужным именем имеет
+приоритет. Коллизия нескольких исходников в один итоговый путь блокирует build.
+
+Builder переписывает root-relative ссылки на `jpg`, `jpeg`, `png`, `webp`,
+`avif`, `gif`, `svg`, `mov`, `webm` и `mp4`. Внешние URL, шрифты и прочие
+root-relative ресурсы не изменяются.
+
+Файлы подключаются от корня:
 
 ```html
-<img src="/hero.webp" alt="">
+<img src="/images/hero.webp" alt="">
 ```
 
 ```css
-.hero {
-  background-image: url("/hero.webp");
-}
+.hero { background-image: url("/images/hero.webp"); }
 ```
 
-В dev пути направляются на фактический origin текущего Vite-сервера. При
-production build они
-преобразуются в `<assetsBase>/landing-pages/<folder>/...`. Builder
-переписывает изображения `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `svg` и
-видео `mov`, `webm`, `mp4`; остальные root-relative ресурсы не изменяются.
+Вложенная структура сохраняется: `public/hotels/room.webp` публикуется как
+`landing-pages/<folder>/hotels/room.webp`.
 
-### Deploy assets
+## Deploy ассетов
 
 ```bash
 b2c-landing-vite deploy assets
 ```
 
-Команда выполняет свежую сборку, сравнивает build manifest с deploy-state и CDN,
-а затем показывает план загрузки. Перед отправкой файлов требуется явное
-подтверждение; по умолчанию выбран отказ.
+Команда выполняет свежий build, сравнивает manifest с deploy-state и CDN,
+показывает план и запрашивает подтверждение новых загрузок. По умолчанию выбран
+ответ `No`. Deploy-state обновляется атомарно только после успешной загрузки
+всего плана.
+
+### Immutable CDN
+
+Существующие CDN-файлы не перезаписываются и не удаляются. Новое содержимое нужно
+публиковать под новым именем и обновлять ссылку.
+
+Если локальный файл изменился, а тот же путь уже занят на CDN, команда сообщает
+immutable conflict и не обновляет state. При частичном сетевом сбое она выводит
+уже загруженные пути, но также не принимает новый state целиком.
+
+## Dry-run
+
+```bash
+b2c-landing-vite deploy --dry-run
+b2c-landing-vite deploy --dry-run --section hero
+```
+
+Dry-run выполняет свежий локальный build, читает CDN и CMS и показывает
+фактический план ассетов, страницу, placement и операции над виджетами. Он не
+загружает ассеты, не создаёт checkout, не изменяет CMS и не записывает
+deploy-state, binding или pending-журнал.
+
+Каталог `@CMS/` при этом обновляется, поскольку dry-run начинается с build.
+
+## Полный deploy
+
+```bash
+b2c-landing-vite deploy
+b2c-landing-vite deploy --section hero
+```
+
+Deploy последовательно выполняет свежий build, синхронизацию ассетов и CMS
+operation plan. CMS не меняется, если обязательная загрузка ассетов отменена или
+завершилась ошибкой. Перед CMS builder проверяет наличие всех manifest-ассетов
+на CDN.
+
+### Страница и checkout
+
+При первом запуске можно создать страницу или выбрать существующую. Builder
+сохраняет `pageId`, `layoutAreaId` и позицию в binding-файле. Затем:
+
+- Published выбирается по умолчанию;
+- из Published или Unpublished создаётся Checkout;
+- существующий Checkout обновляется напрямую;
+- потерянную привязку можно восстановить интерактивным выбором.
+
+При пустом CMS-плане checkout не создаётся.
+
+### Согласование local, remote и base
+
+Builder сравнивает:
+
+- `local` — текущие файлы `@CMS/`;
+- `remote` — управляемые виджеты выбранной версии;
+- `base` — подтверждённый снимок последнего deploy.
+
+Независимые изменения разных секций объединяются. Конкурирующее изменение одной
+секции не перезаписывается молча: нужно сохранить remote, явно применить local
+или отменить deploy. Без `base` различие local и remote также считается
+потенциальным конфликтом.
+
+### Operation plan и публикация
+
+Перед записью показывается исполнимый план добавления, обновления, перестановки и
+удаления управляемых виджетов. Он строится по фактическому checkout и повторно
+проверяется после подготовки версии. Подтверждение по умолчанию — `No`.
+
+Изменяющие Backoffice-запросы автоматически не повторяются. После синхронизации
+builder предлагает публикацию. Для неё должны быть заполнены title, URL, SEO
+title и SEO description. В конце выводятся Preview, Backoffice URL и, после
+публикации, live URL.
+
+### Deploy одной секции
+
+`deploy --section <key>` ограничивает reconciliation и CMS-план указанной
+секцией. Соседние секции не обновляются и не удаляются. Asset-стадия остаётся
+полной: builder собирает и проверяет весь manifest.
+
+Pending полного deploy нельзя продолжить через `--section`, и наоборот: resume
+требует исходный scope.
+
+### Частичная ошибка и resume
+
+Перед первой CMS-операцией создаётся pending-журнал. После каждой подтверждённой
+операции в него атомарно записываются deployment id, scope, checkout placement,
+binding, завершённые операции и ожидаемая ревизия.
 
-Вложенная структура `public/` сохраняется на CDN. Например,
-`public/hotels/gallery/room.webp` загружается как
-`landing-pages/<folder>/hotels/gallery/room.webp`.
+После ошибки следующий deploy того же scope открывает тот же checkout,
+перечитывает его и продолжает по свежему фактическому плану. Новый checkout не
+создаётся. После полного успеха pending удаляется.
 
-Существующие CDN-файлы не перезаписываются и не удаляются. Если содержимое
-изменилось, файл нужно переименовать, чтобы опубликовать его по новому URL.
-Deploy-state обновляется атомарно только после успешной загрузки всех файлов.
-В итоговом блоке команда также выводит корневой URL `CDN folder`, например
-`https://b2ccdn.coral.ru/content/landing-pages/uae-promo/`.
+### Revision guard и ограничения
 
-Обычный `deploy` выполняет этот же план синхронизации ассетов перед изменением
-CMS. Если нужны новые файлы, он запрашивает подтверждение загрузки и продолжает
-CMS-deploy только после её успешного завершения. При отказе CMS не изменяется.
-Отдельная команда `deploy assets` полезна, когда нужно загрузить файлы заранее,
-не меняя CMS.
+Перед каждой операцией, перед resume и после последней операции builder повторно
+читает checkout и сравнивает ревизию. При несовпадении следующая операция не
+запускается, а pending сохраняется для проверки.
 
-Перед изменением CMS команда показывает план добавления, обновления, удаления и
-перестановки управляемых виджетов. Подтверждение и последующее предложение
-публикации по умолчанию имеют значение `No`. После deploy выводятся Preview и
-прямая ссылка на созданную checkout-версию в BackOffice.
+Это best-effort защита, не транзакционная блокировка. Без используемого ETag или
+server-side lock остаются:
 
-## Совместимость
+- TOCTOU-окно между контрольным GET и изменяющим запросом;
+- окно между успешной CMS-операцией и записью pending-журнала.
+
+После такого сбоя проверьте checkout в Backoffice перед повторным deploy.
+
+### Локальная блокировка
+
+Lock не допускает параллельные deploy одного проекта на одном компьютере, но не
+защищает от другого клона или ручных действий в Backoffice. Lock старше двух
+часов или от завершившегося процесса считается устаревшим.
+
+## Служебные файлы
+
+| Путь | Назначение | Git |
+| --- | --- | --- |
+| `.b2c/dev-port` | Локальный dev-порт | Не хранить |
+| `.b2c/deploy/<site>--<folder>.state.json` | Хэши ассетов и CMS base | Хранить для общего state команды |
+| `.b2c/deploy/<site>--<folder>.binding.json` | Привязка к странице и layout area | Хранить, если привязка общая |
+| `.b2c/deploy/<site>--<folder>.pending.json` | Незавершённый deploy | Не хранить |
+| `.b2c/deploy/<site>--<folder>.lock` | Локальная блокировка | Не хранить; удаляется автоматически |
+
+Не редактируйте pending и lock во время работающего deploy.
+
+## Аутентификация и окружение
+
+При первом обращении к Backoffice builder запрашивает ADFS login и скрытый
+password. Сохраняется только access token, отдельно для каждого бренда, максимум
+на 23 часа. Путь по умолчанию: `~/.b2c-landing-vite/auth.json`.
+
+| Переменная | Назначение |
+| --- | --- |
+| `B2C_BACKOFFICE_TOKEN` | Готовый token без ADFS login |
+| `B2C_BACKOFFICE_LOGIN` | Login для неинтерактивного входа |
+| `B2C_BACKOFFICE_PASSWORD` | Password для неинтерактивного входа |
+| `B2C_AUTH_CACHE` | Другой путь к token cache |
+| `B2C_PORT` | Обязательный dev-порт |
+| `B2C_NO_OPEN=1` | Не открывать вкладки автоматически |
+
+Не добавляйте cache, пароли и токены в Git. Backoffice GET-запросы имеют timeout
+30 секунд и до двух повторов при сетевой ошибке, timeout, HTTP 429, 502, 503 или
+504. Изменяющие запросы не повторяются.
+
+## Обновления
+
+```bash
+b2c-landing-vite update
+```
+
+Команда проверяет npm registry и печатает инструкции, но ничего не устанавливает.
+Короткая проверка также выполняется после рабочих команд; ошибка registry не
+меняет их результат.
+
+```bash
+npm install --global @coraltravelcenter/b2c-landing-builder@latest
+npx @coraltravelcenter/create-b2c-landing-vite@latest migrate
+```
 
-Builder проверяет `schemaVersion` до запуска команд. Несовместимая версия схемы
-блокирует работу. Для аварийной сборки старого проекта можно использовать:
+Аварийная сборка конкретной версией:
 
 ```bash
 npx @coraltravelcenter/b2c-landing-builder@<version> build
 ```
 
-## Разработка пакета
+## Диагностика
+
+- **Missing local dependency:** установите зависимость выбранного стека в проект.
+- **Port already in use:** остановите процесс или задайте свободный `B2C_PORT`.
+- **Backoffice is unavailable:** подключитесь к офисной сети или VPN.
+- **Immutable asset conflict:** переименуйте файл и обновите ссылки.
+- **Remote CMS changes:** сравните local и remote и явно выберите стратегию.
+- **Incomplete deploy:** повторите deploy с тем же scope; при revision conflict
+  сначала проверьте checkout и не удаляйте pending ради обхода защиты.
+
+## Справочник команд
+
+Все команды выполняются из корня проекта.
+
+| Команда | Результат |
+| --- | --- |
+| `b2c-landing-vite check` | Проверить проект |
+| `b2c-landing-vite check --strict` | Проверить static/initializer-контракт |
+| `b2c-landing-vite dev` | Запустить Vite и userscript |
+| `b2c-landing-vite build` | Собрать `@CMS/`, ассеты и manifest |
+| `b2c-landing-vite deploy assets` | Синхронизировать только CDN-ассеты |
+| `b2c-landing-vite deploy --dry-run` | Показать полный CDN/CMS-план |
+| `b2c-landing-vite deploy --dry-run --section <key>` | Показать план секции |
+| `b2c-landing-vite deploy` | Синхронизировать ассеты и CMS |
+| `b2c-landing-vite deploy --section <key>` | Синхронизировать ассеты и одну секцию |
+| `b2c-landing-vite block:add <key>` | Создать блок |
+| `b2c-landing-vite block:rename <old> <new>` | Переименовать блок |
+| `b2c-landing-vite update` | Показать ручные обновления |
+
+## Разработка builder
 
 ```bash
 npm ci
 npm test
 npm run check
 npm run build
+npm run test:dev
 npm pack --dry-run
 ```
 
-Pull request проверяется на Node.js 20.19 и 22. Prerelease публикуется с npm
-dist-tag `next`, стабильная версия — с `latest`.
+Инструкции по публикации: [RELEASING.md](./RELEASING.md).