# C4-Builder

* [Обзор](#%D0%9E%D0%B1%D0%B7%D0%BE%D1%80)
  * [01 Быстрый старт](#01-%D0%91%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82)
  * [02 Проект](#02-%D0%9F%D1%80%D0%BE%D0%B5%D0%BA%D1%82)
  * [03 Диаграммы](#03-%D0%94%D0%B8%D0%B0%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D1%8B)
  * [04 Выводы](#04-%D0%92%D1%8B%D0%B2%D0%BE%D0%B4%D1%8B)
  * [05 CLI и конфигурация](#05-CLI-%D0%B8-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D1%8F)
  * [06 Плагины](#06-%D0%9F%D0%BB%D0%B0%D0%B3%D0%B8%D0%BD%D1%8B)
  * [07 Docker и CI](#07-Docker-%D0%B8-CI)
  * [08 Агенты](#08-%D0%90%D0%B3%D0%B5%D0%BD%D1%82%D1%8B)
  * [09 Разработка](#09-%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0)
  * [Журнал решений](#%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB-%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9)
    * [Changes](#Changes)
    * [Specs](#Specs)
      * [agent-skills](#agent-skills)
      * [bpmn-diagrams](#bpmn-diagrams)
      * [build-pipeline](#build-pipeline)
      * [ci-validation](#ci-validation)
      * [cli-commands](#cli-commands)
      * [config-validation](#config-validation)
      * [dev-toolchain](#dev-toolchain)
      * [diagram-rendering](#diagram-rendering)
      * [docs-site](#docs-site)
      * [jre-resolution](#jre-resolution)
      * [offline-site](#offline-site)
      * [openapi-plugin](#openapi-plugin)
      * [openspec-plugin](#openspec-plugin)
      * [output-formats](#output-formats)
      * [plugin-system](#plugin-system)
      * [project-scaffold](#project-scaffold)
      * [project-template](#project-template)
      * [regression-testing](#regression-testing)
      * [release-publishing](#release-publishing)
    * [Archive](#Archive)
      * [2026-10-06-docs-site](#2026-10-06-docs-site)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [docs-site](#docs-site)
      * [2026-10-06-bpmn-diagrams](#2026-10-06-bpmn-diagrams)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [bpmn-diagrams](#bpmn-diagrams)
          * [diagram-rendering](#diagram-rendering)
          * [project-template](#project-template)
          * [regression-testing](#regression-testing)
      * [2026-10-03-pr8-review-fixes](#2026-10-03-pr8-review-fixes)
        * [tasks](#tasks)
        * [README](#README)
      * [2026-10-03-plugin-system](#2026-10-03-plugin-system)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [openapi-plugin](#openapi-plugin)
          * [openspec-plugin](#openspec-plugin)
          * [plugin-system](#plugin-system)
      * [2026-10-03-plantuml-1-2026-8](#2026-10-03-plantuml-1-2026-8)
        * [tasks](#tasks)
      * [2026-10-03-offline-site-assets](#2026-10-03-offline-site-assets)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [offline-site](#offline-site)
          * [openapi-plugin](#openapi-plugin)
      * [2026-10-03-node-22](#2026-10-03-node-22)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [dev-toolchain](#dev-toolchain)
      * [2026-10-03-llms-txt](#2026-10-03-llms-txt)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [output-formats](#output-formats)
          * [project-scaffold](#project-scaffold)
      * [2026-10-03-cli-fixes](#2026-10-03-cli-fixes)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [cli-commands](#cli-commands)
      * [2026-10-03-cli-english-messages](#2026-10-03-cli-english-messages)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [cli-commands](#cli-commands)
      * [2026-10-03-agent-skills](#2026-10-03-agent-skills)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [agent-skills](#agent-skills)
          * [cli-commands](#cli-commands)
          * [project-template](#project-template)
      * [2026-07-24-nimbus-font-system-flag](#2026-07-24-nimbus-font-system-flag)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [diagram-rendering](#diagram-rendering)
      * [2026-07-09-tag-driven-rc-publish](#2026-07-09-tag-driven-rc-publish)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [release-publishing](#release-publishing)
      * [2026-07-08-zod-and-deps-upgrade](#2026-07-08-zod-and-deps-upgrade)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [config-validation](#config-validation)
          * [dev-toolchain](#dev-toolchain)
      * [2026-07-07-ts-port-full](#2026-07-07-ts-port-full)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [build-pipeline](#build-pipeline)
      * [2026-07-07-build-split](#2026-07-07-build-split)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [build-pipeline](#build-pipeline)
      * [2026-07-05-ts-scaffold](#2026-07-05-ts-scaffold)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [build-pipeline](#build-pipeline)
          * [ci-validation](#ci-validation)
          * [dev-toolchain](#dev-toolchain)
      * [2026-07-05-resvg-png](#2026-07-05-resvg-png)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [diagram-rendering](#diagram-rendering)
      * [2026-07-05-remove-vscode-snippets](#2026-07-05-remove-vscode-snippets)
        * [design](#design)
        * [tasks](#tasks)
        * [README](#README)
        * [specs](#specs)
          * [project-scaffold](#project-scaffold)
      * [2026-07-05-remove-plantuml-version](#2026-07-05-remove-plantuml-version)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [diagram-rendering](#diagram-rendering)
      * [2026-07-05-remove-pdf](#2026-07-05-remove-pdf)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [output-formats](#output-formats)
      * [2026-07-05-new-noninteractive](#2026-07-05-new-noninteractive)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [project-scaffold](#project-scaffold)
      * [2026-07-05-jre-resolver](#2026-07-05-jre-resolver)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [diagram-rendering](#diagram-rendering)
          * [jre-resolution](#jre-resolution)
      * [2026-07-05-golden-matrix](#2026-07-05-golden-matrix)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [regression-testing](#regression-testing)
      * [2026-07-05-dev-toolchain](#2026-07-05-dev-toolchain)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [ci-validation](#ci-validation)
          * [dev-toolchain](#dev-toolchain)
      * [2026-07-05-d2-backend](#2026-07-05-d2-backend)
        * [design](#design)
        * [tasks](#tasks)
        * [README](#README)
        * [specs](#specs)
          * [diagram-rendering](#diagram-rendering)
          * [regression-testing](#regression-testing)
      * [2026-07-04-template-offline](#2026-07-04-template-offline)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [project-template](#project-template)
      * [2026-07-04-plantuml-java-direct](#2026-07-04-plantuml-java-direct)
        * [design](#design)
        * [tasks](#tasks)
        * [README](#README)
        * [specs](#specs)
          * [ci-validation](#ci-validation)
          * [diagram-rendering](#diagram-rendering)
          * [regression-testing](#regression-testing)
      * [2026-07-04-golden-test-ci](#2026-07-04-golden-test-ci)
        * [design](#design)
        * [tasks](#tasks)
        * [specs](#specs)
          * [ci-validation](#ci-validation)
          * [regression-testing](#regression-testing)

---

## Обзор

# C4-Builder

**Архитектура как код, которую агент пишет, проверяет и читает.**

C4-Builder — CLI, который собирает папку с markdown и диаграммами PlantUML, D2 или BPMN в
документацию: сайт на docsify, markdown по папкам или один файл. Папки задают иерархию
[C4-модели](https://c4model.com/) (система → контейнер → компонент), а git хранит историю
архитектурных решений вместе с кодом: правка архитектуры проходит ревью в pull request,
как любое другое изменение.

Этот сайт собран самим c4builder из папки `docs/` репозитория, диаграммы на нём
отрендерены при сборке в CI.

```plantuml
@startuml
!include <C4/C4_Context>
!include styles.iuml

LAYOUT_TOP_DOWN()

Person(dev, "Разработчик", "Пишет markdown и диаграммы, ревьюит архитектуру в pull request")
Person(agent, "AI-агент", "Claude Code, Codex, Cursor: правит модель и проверяет её через c4builder check")

System(c4b, "C4-Builder", "CLI: собирает папку markdown + PlantUML/D2 в документацию, проверяет отдельные диаграммы")

System_Ext(engines, "Движки диаграмм", "PlantUML (вендорный jar + Java, Smetana), D2 (WASM)")
System_Ext(openspec, "OpenSpec-store", "Спеки и change'и проекта: proposal, design, tasks")
System_Ext(openapi, "OpenAPI-контракты", "Спеки сервисов: папка или архив репозитория")
System_Ext(site, "Docsify-сайт", "Статика без CDN: GitHub Pages, GitLab Pages, любой веб-сервер")
System_Ext(md, "Markdown", "README по папкам или один файл для репозитория")

Rel(dev, c4b, "Собирает и смотрит", "c4builder --site -w")
Rel(agent, c4b, "Проверяет правки", "c4builder check")
Rel(c4b, engines, "Рендерит диаграммы", "локально, без сети")
Rel(c4b, openspec, "Публикует раздел", "плагин openspec")
Rel(c4b, openapi, "Публикует swagger-ui", "плагин openapi")
Rel(c4b, site, "Собирает")
Rel(c4b, md, "Собирает")

SHOW_LEGEND()
@enduml
```

## Чем форк отличается от upstream

Оригинальный C4-Builder не развивается: последний коммит — март 2024 года, последний
npm-релиз `c4builder` 0.2.16 вышел в 2022-м. В Альфа-Капитале на нём собирается
архитектурный репозиторий на сотню с лишним диаграмм, поэтому мы продолжаем проект как
поддерживаемый форк и развиваем его под работу с AI-агентами:

- **Детерминированный офлайн-рендер.** PlantUML-jar, шрифт и движки поставляются с пакетом,
  раскладку считает встроенный в PlantUML движок Smetana, Graphviz не нужен. Одни и те же
  исходники дают одинаковые SVG на ноутбуке, в CI и в Docker, а сеть при сборке не нужна.
- **`c4builder check` — обратная связь за секунды.** Проверяет отдельные диаграммы тем же
  движком, что и сборка, и возвращает код выхода и номер строки с ошибкой. Агент правит
  `.puml` и сразу узнаёт, сломал ли он что-нибудь, без человека и без полной сборки.
- **Плагины.** `openspec` публикует спеки и change'и рядом с C4-моделью, `openapi` —
  контракты сервисов офлайн-страницами swagger-ui.
- **D2** вторым движком диаграмм, PNG через resvg, Java по желанию: если её нет, c4builder
  скачает JRE сам.
- **BPMN-процессы** третьим движком: агент пишет BPMN 2.0 XML без координат, сборка проверяет
  модель и раскладывает её с горизонтальными пулами и дорожками.
- **Инженерная база.** TypeScript, golden-снапшоты рендера, CI на каждый pull request,
  npm-пакет и Docker-образ по тегу релиза.

Полный список изменений — в
[CHANGELOG](https://github.com/AlfaCapital-Tech/C4-Builder/blob/master/CHANGELOG.md).

## Цикл с агентом

1. Агент (или вы) правит `.md` и `.puml` в `src/`.
2. `c4builder check <файлы>` отвечает, собирается ли диаграмма, и показывает строку ошибки.
3. `c4builder --site -w` пересобирает сайт на каждое сохранение и обновляет браузер.

Скиллы для агентов, `AGENTS.md` в новом проекте и `llms.txt` с исходниками диаграмм — на
странице [Агенты](08%20Агенты/08%20Агенты.md).

## Разделы

- [Быстрый старт](01%20Быстрый%20старт/01%20Быстрый%20старт.md) — установка и первый проект.
- [Проект](02%20Проект/02%20Проект.md) — как папки и файлы превращаются в страницы.
- [Диаграммы](03%20Диаграммы/03%20Диаграммы.md) — PlantUML, D2, BPMN, шрифты, PNG, проверка.
- [Выводы](04%20Выводы/04%20Выводы.md) — сайт, markdown по папкам, один файл.
- [CLI и конфигурация](05%20CLI%20и%20конфигурация/05%20CLI%20и%20конфигурация.md) — команды
  и ключи `.c4builder`.
- [Плагины](06%20Плагины/06%20Плагины.md) — `openspec`, `openapi`, свой плагин.
- [Docker и CI](07%20Docker%20и%20CI/07%20Docker%20и%20CI.md) — образ и сборка в пайплайне.
- [Разработка](09%20Разработка/09%20Разработка.md) — как устроен и выпускается c4builder.
- **Журнал решений** — OpenSpec-store этого репозитория: почему c4builder устроен именно так.

## Благодарности

C4-Builder создал Adrian Victor Lupu; проект распространяется
по лицензии MIT. Форк сохраняет лицензию, авторство и историю: изменения upstream со ссылками
на исходные pull request'ы перечислены в CHANGELOG.


## 01 Быстрый старт

[Обзор](#C4-Builder)

# Быстрый старт

## Установка

```bash
npm i -g @alfacapital-tech/c4builder
```

Нужен Node.js 22.17 или новее. `npm install` без тега ставит последний стабильный релиз.

Для рендера PlantUML нужна Java 17+. Если `java` есть в `JAVA_HOME` или в `PATH`, c4builder
возьмёт её; если нет — при первой сборке скачает приватную JRE (Temurin) в свой кэш.
Graphviz не нужен: раскладку считает встроенный в PlantUML движок Smetana. PlantUML-jar и шрифт
диаграмм входят в пакет.

```bash
c4builder jre info      # какая Java будет использована (JSON: версия, путь кэша)
c4builder jre install   # скачать JRE заранее: перед работой офлайн или в образ CI
```

Если ставить Node и Java не хочется, есть [Docker-образ](07%20Docker%20и%20CI/07%20Docker%20и%20CI.md),
в нём уже всё есть.

## Первый проект

```bash
c4builder --new --name demo -y # проект из шаблона с готовым конфигом, без вопросов
cd demo
c4builder                      # сборка в docs/
c4builder site                 # сайт на http://localhost:3000
```

Без `-y` c4builder спросит имя проекта, а первая сборка проведёт через мастер настройки.
С версии 0.5.0 то же самое можно писать короче — `c4builder new --name demo -y`; в 0.4.0
позиционной формы нет, там только флаг `--new`.

В новом проекте лежит демо «Internet Banking System» из C4-модели: контекст, контейнеры,
deployment, динамическая диаграмма, sequence, class и ditaa, страница с кириллицей, пример
на D2 и BPMN-процесс «Открытие счёта». Все C4-диаграммы подключают библиотеку через stdlib (`!include <C4/C4_Container>`):
C4-PlantUML встроен в jar, поэтому сборке не нужен интернет. Рядом с `src/` лежит `AGENTS.md` —
инструкция для AI-агентов, как собирать и проверять диаграммы (с версии 0.5.0, в документацию
не попадает).

## Живой предпросмотр

```bash
c4builder --site -w
```

Собирает проект, поднимает локальный сервер и пересобирает сайт на каждое сохранение в `src/`.
Браузер перезагружается сам и сохраняет позицию прокрутки. `-o` открывает браузер,
`-p 8080` меняет порт.

## Изменить настройки

`c4builder --config` (с 0.5.0 — и `c4builder config`) снова запускает мастер, подставляя
текущие значения;
`c4builder --list` показывает конфиг. `.c4builder` — обычный JSON, его можно править руками:
все ключи описаны на странице [CLI и конфигурация](05%20CLI%20и%20конфигурация/05%20CLI%20и%20конфигурация.md).

## Релиз-кандидаты

Пре-релизы `X.Y.Z-rc.N` публикуются под npm-тегом `rc` и не трогают `latest`:

```bash
npm i -g @alfacapital-tech/c4builder@rc
```

Чтобы вернуться на стабильную версию, поставьте пакет с тегом `latest`.


## 02 Проект

[Обзор](#C4-Builder)

# Проект

Проект c4builder — это папка с файлом `.c4builder`. В ней две главные папки: **исходники**
(`src`, ключ `rootFolder`) и **выход** (`docs`, ключ `distFolder`). Все команды запускаются из
папки проекта: пути в конфиге считаются от неё.

## Папка = страница

Каждая папка внутри исходников — одна страница документации. По C4-модели это обычно
система, контейнер или компонент, но подойдёт любая тема: ADR, глоссарий, runbook.

```text
demo/
├── .c4builder              конфиг проекта
├── docs/                   выход: пересоздаётся при каждой сборке
└── src/                    исходники
    ├── context.md          корень = главная страница
    ├── context.puml
    ├── styles.iuml         общая тема диаграмм (подключается через !include)
    └── 1 Internet Banking System/
        ├── system.md
        ├── system.puml
        └── API Application/
            ├── container.md
            └── container.puml
```

Сборка обходит дерево и склеивает все `.md` и диаграммы папки в одну страницу:

- **Заголовок страницы** — имя папки. Если первый `.md` начинается со своего `# Заголовка`,
  берётся он.
- **Порядок страниц** — порядок файловой системы. Чтобы задать его явно, используйте
  числовые префиксы: `1 Контекст`, `2 Контейнеры`. Префикс виден в заголовке в sidebar.
- **Диаграммы** вставляются картинками. По умолчанию — перед текстом страницы, после текста —
  с `diagramsOnTop: false`.
- **Диаграмму можно поставить в любое место текста** ссылкой на её исходник:
  `![контейнеры](container.puml)`. Такая диаграмма в общий блок уже не попадает.
- **Файлы и папки с префиксом `_`** не становятся страницами и не рендерятся отдельно, но
  доступны для `!include` и D2-импортов. Это место для общих библиотек: `_c4lib.d2`, `_common.iuml`.
- **Прочие файлы** (картинки, вложения) копируются в выход рядом со страницей, если не
  включён `excludeOtherFiles`. Картинку кладите рядом с `.md`, который на неё ссылается.

## Служебные файлы

| Файл | Зачем | В git |
|---|---|---|
| `.c4builder` | конфиг проекта | да |
| `.c4builder.cache` | чексуммы диаграмм: неизменённые не рендерятся заново | нет |
| `.c4builder.lock` | лок сборки: две сборки в одной папке не пишут выход одновременно | нет |
| `docs_bk/` | копия прошлого выхода на время сборки; при ошибке остаётся как резерв | нет |

Папку выхода c4builder удаляет и создаёт заново на каждой сборке, поэтому своё туда не
кладите. Коммитить ли сам выход, зависит от вывода: markdown по папкам удобно держать в
репозитории, сайт обычно собирается в CI.


## 03 Диаграммы

[Обзор](#C4-Builder)

# Диаграммы

Движок выбирается по расширению файла: `.puml` рендерит PlantUML, `.d2` — D2, `.bpmn` —
BPMN-движок. Форматы могут жить в одном проекте и даже в одной папке, если у файлов разные
имена.

## PlantUML

c4builder запускает вендорный PlantUML-jar напрямую через `java`, раскладку считает встроенный
движок Smetana. Graphviz ставить не нужно. Версия jar зафиксирована в пакете, поэтому
обновление PlantUML на машине разработчика сборку не меняет.

**C4 без интернета.** Библиотека C4-PlantUML встроена в jar, подключайте её через stdlib:

```puml
@startuml
!include <C4/C4_Container>
!include ../styles.iuml

Person(user, "Клиент")
System(bank, "Интернет-банк")
Rel(user, bank, "Пользуется", "HTTPS")
@enduml
```

**Общие стили** — в `.iuml`: `skinparam`, `UpdateElementStyle(...)`, свои макросы. Подключаются
после C4-инклюда относительным путём. Пути в `!include` считаются от папки диаграммы, а не от
корня проекта.

**Кириллица** работает в подписях, описаниях и именах папок: шрифт диаграмм её содержит.

**ditaa** (`@startditaa`) тоже поддерживается и всегда рендерится в PNG.

## Диаграмма прямо в странице

Блок ```` ```plantuml ```` в `.md`-странице рендерится при сборке так же, как файл `.puml`: в
сайте, markdown-коллекции и общем документе на его месте будет картинка, а не текст блока.
`@startuml`/`@enduml` можно опустить, `!include` считаются от папки страницы. Блок с ошибкой
сборку не роняет: на месте картинки — заглушка, в логе — предупреждение с путём `.md`-файла.

Чтобы показать исходник диаграммы как код, пометьте блок `puml` или `text`: такие блоки,
как и ```` ```d2 ````, остаются кодом.

## Детерминизм и шрифт

Диаграммы рисуются вендорным шрифтом Nimbus Sans (метрики Helvetica, кириллица, греческий),
а не системным. Поэтому одна и та же диаграмма даёт одинаковую геометрию на macOS, Linux,
в CI и в Docker, а дифф SVG в pull request показывает только реальные изменения.

`useSystemFonts: true` в `.c4builder` (или `--system-fonts` на один запуск) включает системные
шрифты. Вид станет привычнее, но результат будет зависеть от машины.

## Кэш рендера

Неизменённые диаграммы при повторной сборке не рендерятся: c4builder хранит чексуммы в
`.c4builder.cache`. В чексумму входят исходник, все локальные `!include` и D2-импорты, путь
выхода и параметры рендера, для D2 и BPMN — ещё версии пакетов движка. Правка общего `styles.iuml` перерисует все диаграммы, которые
его подключают, и только их.

## D2

[D2](https://d2lang.com) рендерится через WASM-сборку движка прямо в Node — без внешних
бинарников. Ссылка из markdown такая же, как для PlantUML: `![схема](landscape.d2)`.

- Движок — опциональная зависимость `@terrastruct/d2` (~60 МБ). npm ставит её вместе с
  c4builder, а загружается она только если в проекте есть `.d2`. Если пакета нет (например,
  установка шла с `--omit=optional`), сборка остановится с подсказкой `npm install @terrastruct/d2`.
- [Импорты](https://d2lang.com/tour/imports) `@file` и `...@file` разрешает сам c4builder,
  сеть не нужна. Общую библиотеку классов назовите с `_` (`_c4lib.d2`), чтобы она не
  рендерилась отдельной диаграммой: `...@../_c4lib`.
- Раскладка — ключ `d2Layout`: `dagre` (по умолчанию) или `elk`.

## BPMN

`.bpmn` — бизнес-процесс в нотации BPMN 2.0: события, задачи, шлюзы, горизонтальные пулы и
дорожки, message flow между участниками. Ссылка из markdown обычная: `![процесс](process.bpmn)`.

**Пишется только семантика.** Файл — стандартный BPMN 2.0 XML: `collaboration` с участниками
(пулами) и message flow, `process` с `laneSet`, узлами и sequence flow. Координаты (секция
`bpmndi:BPMNDiagram`) не нужны, а если они есть — игнорируются: раскладку всегда делает
сборка. Элементы `incoming`/`outgoing` писать не обязательно, связи берутся из
`sourceRef`/`targetRef`.

```xml
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                  id="Definitions_1" targetNamespace="https://example.com/bpmn">
  <bpmn:process id="Process_1" name="Заявка" isExecutable="false">
    <bpmn:startEvent id="Start" name="Заявка получена" />
    <bpmn:userTask id="Check" name="Проверить заявку" />
    <bpmn:endEvent id="End" name="Заявка обработана" />
    <bpmn:sequenceFlow id="Flow_1" sourceRef="Start" targetRef="Check" />
    <bpmn:sequenceFlow id="Flow_2" sourceRef="Check" targetRef="End" />
  </bpmn:process>
</bpmn:definitions>
```

**Пример** — процесс открытия счёта из шаблона `c4builder new`: два пула, дорожки, обмен
сообщениями с бюро кредитных историй, таймер-эскалация. В файле только семантика, раскладку и
рендер сделала эта сборка:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Только семантическая часть BPMN: координат (bpmndi) нет, раскладку делает c4builder. -->
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
                  id="Definitions_AccountOpening"
                  targetNamespace="https://example.com/bpmn/account-opening">
  <bpmn:collaboration id="Collaboration_AccountOpening">
    <bpmn:participant id="Pool_Bank" name="Банк" processRef="Process_AccountOpening" />
    <bpmn:participant id="Pool_CreditBureau" name="Бюро кредитных историй" />
    <bpmn:messageFlow id="Message_HistoryRequest" name="Запрос истории"
                      sourceRef="Task_RequestHistory" targetRef="Pool_CreditBureau" />
    <bpmn:messageFlow id="Message_CreditReport" name="Кредитный отчёт"
                      sourceRef="Pool_CreditBureau" targetRef="Task_ReceiveReport" />
  </bpmn:collaboration>

  <bpmn:process id="Process_AccountOpening" name="Открытие счёта" isExecutable="false">
    <bpmn:laneSet id="LaneSet_Bank">
      <bpmn:lane id="Lane_Client" name="Клиент">
        <bpmn:flowNodeRef>Start_AccountNeeded</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_SubmitApplication</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>End_AccountOpened</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>End_Rejected</bpmn:flowNodeRef>
      </bpmn:lane>
      <bpmn:lane id="Lane_FrontOffice" name="Фронт-офис">
        <bpmn:flowNodeRef>Task_CheckDocuments</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_RequestHistory</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_ReceiveReport</bpmn:flowNodeRef>
      </bpmn:lane>
      <bpmn:lane id="Lane_BackOffice" name="Бэк-офис">
        <bpmn:flowNodeRef>Task_Assess</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Timer_AssessOverdue</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_Escalate</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>End_Escalated</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Gateway_Decision</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_OpenAccount</bpmn:flowNodeRef>
        <bpmn:flowNodeRef>Task_PrepareRejection</bpmn:flowNodeRef>
      </bpmn:lane>
    </bpmn:laneSet>

    <bpmn:startEvent id="Start_AccountNeeded" name="Нужен счёт" />
    <bpmn:userTask id="Task_SubmitApplication" name="Подать заявку" />
    <bpmn:userTask id="Task_CheckDocuments" name="Проверить документы" />
    <bpmn:sendTask id="Task_RequestHistory" name="Запросить кредитную историю" />
    <bpmn:receiveTask id="Task_ReceiveReport" name="Получить кредитный отчёт" />
    <bpmn:userTask id="Task_Assess" name="Оценить заявку" />
    <bpmn:boundaryEvent id="Timer_AssessOverdue" name="3 рабочих дня" attachedToRef="Task_Assess">
      <bpmn:timerEventDefinition id="TimerDef_AssessOverdue" />
    </bpmn:boundaryEvent>
    <bpmn:task id="Task_Escalate" name="Эскалировать руководителю" />
    <bpmn:endEvent id="End_Escalated" name="Заявка у руководителя" />
    <bpmn:exclusiveGateway id="Gateway_Decision" name="Одобрить?" />
    <bpmn:serviceTask id="Task_OpenAccount" name="Открыть счёт" />
    <bpmn:task id="Task_PrepareRejection" name="Подготовить отказ" />
    <bpmn:endEvent id="End_AccountOpened" name="Счёт открыт" />
    <bpmn:endEvent id="End_Rejected" name="Получен отказ" />

    <bpmn:sequenceFlow id="Flow_Start" sourceRef="Start_AccountNeeded" targetRef="Task_SubmitApplication" />
    <bpmn:sequenceFlow id="Flow_Submitted" sourceRef="Task_SubmitApplication" targetRef="Task_CheckDocuments" />
    <bpmn:sequenceFlow id="Flow_Checked" sourceRef="Task_CheckDocuments" targetRef="Task_RequestHistory" />
    <bpmn:sequenceFlow id="Flow_Requested" sourceRef="Task_RequestHistory" targetRef="Task_ReceiveReport" />
    <bpmn:sequenceFlow id="Flow_Received" sourceRef="Task_ReceiveReport" targetRef="Task_Assess" />
    <bpmn:sequenceFlow id="Flow_Assessed" sourceRef="Task_Assess" targetRef="Gateway_Decision" />
    <bpmn:sequenceFlow id="Flow_Approved" name="Да" sourceRef="Gateway_Decision" targetRef="Task_OpenAccount" />
    <bpmn:sequenceFlow id="Flow_Declined" name="Нет" sourceRef="Gateway_Decision" targetRef="Task_PrepareRejection" />
    <bpmn:sequenceFlow id="Flow_Opened" sourceRef="Task_OpenAccount" targetRef="End_AccountOpened" />
    <bpmn:sequenceFlow id="Flow_Rejected" sourceRef="Task_PrepareRejection" targetRef="End_Rejected" />
    <bpmn:sequenceFlow id="Flow_Overdue" sourceRef="Timer_AssessOverdue" targetRef="Task_Escalate" />
    <bpmn:sequenceFlow id="Flow_Escalated" sourceRef="Task_Escalate" targetRef="End_Escalated" />
  </bpmn:process>
</bpmn:definitions>
```

**Раскладка** — [bpmn-auto-layout](https://github.com/bpmn-io/bpmn-auto-layout): пулы и
дорожки горизонтальными полосами с подписью слева, поток слева направо, каждый узел в полосе
своей дорожки. Подпроцессы рисуются свёрнутыми — детализацию выносите в отдельный `.bpmn`.
Раскладчик пока в alpha: если он потеряет элемент модели, сборка остановится с ошибкой и id
элементов, а не выпустит урезанную схему. Ручными координатами неудачную раскладку не
поправить — упростите модель или разбейте её на обзор и детализацию.

**Рендер** — [bpmn-js](https://bpmn.io) в стандартной нотации, без браузера и сети. Текст
меряется по вендорному Nimbus Sans, поэтому SVG одинаков на любой машине (режим
`useSystemFonts` на BPMN не влияет), PNG — штатной растеризацией.

**Проверка модели** идёт перед раскладкой — и в сборке, и в `c4builder check`. Набор правил
фиксирован: рекомендованные правила [bpmnlint](https://github.com/bpmn-io/bpmnlint) (кроме
`no-bpmndi`) и правила c4builder:

| Правило | Уровень | Что проверяет |
|---|---|---|
| `no-disconnected`, `start-event-required`, `end-event-required`, `label-required`, … | error | рекомендованный набор bpmnlint |
| `c4builder/lane-membership` | error | у процесса с дорожками каждый узел ровно в одной дорожке |
| `c4builder/sequence-flow-in-pool` | error | sequence flow не пересекает границу пула |
| `c4builder/message-flow-between-pools` | error | message flow соединяет разные пулы |
| `c4builder/gateway-flow-labels` | warning | ветки XOR/inclusive-шлюза подписаны |

Ошибка останавливает рендер диаграммы, предупреждение только печатается. Каждое нарушение —
отдельная строка с id элемента и именем правила:

```text
✗ src/process.bpmn: Task_Check [no-disconnected] Element is not connected
⚠ src/process.bpmn: Flow_No [c4builder/gateway-flow-labels] Outgoing flow of a diverging gateway has no label
```

**Конвенции:** пул — организация (внешняя — пулом без процесса, «чёрным ящиком»), дорожка —
роль или подразделение внутри неё; между пулами только message flow; ветки шлюза подписаны;
вместо диаграммы на 40+ узлов — обзорный процесс и отдельные `.bpmn` для подробностей.

**Зависимости.** Пакеты движка (`bpmn-js`, `bpmn-moddle`, `bpmnlint`, `bpmn-auto-layout`,
`jsdom`) — опциональные: npm ставит их вместе с c4builder, а загружаются они, только если в
проекте есть `.bpmn`. Установка с `--omit=optional` оставляет только ядро — сборка проекта с
`.bpmn` остановится с подсказкой переустановить c4builder без этого флага.

## PNG

С `diagramFormat: png` c4builder рендерит SVG и растеризует его через
[resvg](https://github.com/thx/resvg-js) тем же вендорным шрифтом. PNG получается
одинаковым для PlantUML, D2 и BPMN и не требует браузера. ditaa остаётся нативным PNG PlantUML.

## Онлайн-сервер PlantUML

С `generateLocalImages: false` диаграммы не рендерятся локально: в выход попадают ссылки на
сервер из `plantumlServerUrl` (по умолчанию `https://www.plantuml.com/plantuml`). Это значит,
что исходники диаграмм уходят на внешний сервер, а D2 и BPMN в этом режиме не работают —
сборка остановится с ошибкой. Режим оставлен для совместимости; основной — локальный рендер.

## Проверка отдельных диаграмм

```bash
c4builder check src/context.puml "src/4 D2 Example/landscape.d2"
```

`check` проверяет `.puml`, `.iuml`, `.d2` и `.bpmn` тем же движком, что и сборка (для `.bpmn` —
разбор, правила, раскладка и рендер), но ничего не пишет и не требует проекта или `.c4builder`.
Код выхода 0 — все файлы собираются, 1 — есть ошибка (предупреждения на код не влияют):

```text
✓ src/context.puml
✗ src/system.puml: line 4: Fatal parsing error
```

`!include` разрешается от папки проверяемого файла. Библиотека `.iuml` проверяется включением
в пустую диаграмму, а `.iuml` с макросами C4 (`UpdateElementStyle` и т. п.) — в контексте
C4-stdlib, как в диаграммах, которые его подключают. Номер строки для `.iuml` не печатается.

Pre-commit-хук, который проверяет диаграммы в индексе (`.git/hooks/pre-commit`, пробелы в
путях не мешают):

```bash
#!/bin/sh
git diff --cached --name-only -z --diff-filter=ACM -- '*.puml' '*.iuml' '*.d2' '*.bpmn' | xargs -0 -r c4builder check
```


## 04 Выводы

[Обзор](#C4-Builder)

# Выводы

Форматы выхода включаются независимо, в любом сочетании: мастер спрашивает их при первой
сборке, в `.c4builder` за них отвечают `generateMD`, `generateCompleteMD` и `generateWEB`.
Структура выхода повторяет структуру исходников.

## Сайт на docsify

`generateWEB: true` (по умолчанию). В выходе появляются `index.html`, sidebar с иерархией
страниц и по `.md` на страницу. Сайт статический и не ходит в интернет: docsify, тема и
плагины лежат в `vendor/` рядом с `index.html`, диаграммы — готовыми SVG или PNG. Шрифты
темы — системные (без Google Fonts), emoji вроде `:smile:` — символами, а не картинками с
GitHub, блоки ```` ```plantuml ```` рендерятся при сборке, а не в браузере через plantuml.com.
Внешние адреса появляются только по явному выбору: `generateLocalImages: false` (картинки
диаграмм — ссылками на `plantumlServerUrl`), своя `webTheme` или `docsifyTemplate` с ними,
внешние картинки в тексте страниц.

- Посмотреть локально — `c4builder site` (или `--site -w` с пересборкой), по умолчанию на
  `http://localhost:3000`. Открыть `index.html` двойным щелчком не получится: docsify
  загружает страницы запросами, нужен HTTP-сервер.
- Опубликовать — скопировать папку выхода на любой статический хостинг: GitHub Pages, GitLab
  Pages, nginx. Сборка кладёт `.nojekyll`, чтобы GitHub Pages не прятал файлы с `_`.
- Поиск по сайту — `supportSearch`, ссылка на репозиторий в углу — `repoUrl`, своя тема —
  `webTheme`, свой шаблон `index.html` — `docsifyTemplate`.

Этот сайт — пример такого вывода: см. [Docker и CI](07%20Docker%20и%20CI/07%20Docker%20и%20CI.md),
как он собирается.

## llms.txt для агентов

`generateLLMS: true` (с 0.5.0, нужен сайт) кладёт в корень сайта `llms.txt` — оглавление со
ссылками на `.md` страниц — и `llms-full.txt` — весь текст, где диаграммы вставлены исходниками.
Подробно — на странице [Агенты](08%20Агенты/08%20Агенты.md).

## Markdown по папкам

`generateMD: true` (по умолчанию). В каждой папке выхода — `README.md` со всем текстом и
диаграммами страницы. Такой выход удобно коммитить: GitHub и GitLab показывают его как
обычную документацию репозитория.

Навигация вверху каждого файла:

- `includeTableOfContents` (по умолчанию) — дерево всех страниц, текущая выделена;
- `includeNavigation` — ссылка на родителя и список дочерних страниц.

## Один файл

`generateCompleteMD: true` собирает всё в `<projectName>.md` в корне выхода: оглавление, затем
разделы по страницам, у каждого ссылка на начало. Подходит как единый README архитектуры или
как вход для инструментов, которые читают один файл.

## Как выглядят диаграммы

| Ключ | Что меняет |
|---|---|
| `diagramsOnTop` | диаграммы, которые не вставлены в текст явно, идут до текста (по умолчанию) или после |
| `includeLinkToDiagram` | вместо картинки — ссылка на файл диаграммы |
| `embedDiagram` | картинка встраивается в markdown base64-строкой, рядом ссылка на скачивание |
| `includeBreadcrumbs` | под заголовком страницы — её путь в дереве |
| `excludeOtherFiles` | не копировать в выход картинки и прочие файлы из исходников |
| `diagramFormat` | `svg` (по умолчанию) или `png` |


## 05 CLI и конфигурация

[Обзор](#C4-Builder)

# CLI и конфигурация

## Команды

| Команда | Что делает |
|---|---|
| `c4builder` | собирает проект в текущей папке; без конфига сначала запускает мастер |
| `c4builder --new` | создаёт проект из шаблона в новой папке; с 0.5.0 — и `c4builder new` |
| `c4builder --new --name demo -y` | то же без вопросов: полный конфиг со значениями по умолчанию |
| `c4builder --config` | мастер настройки с текущими значениями; с 0.5.0 — и `c4builder config` |
| `c4builder site` | собирает и раздаёт сайт локально (то же, что `--site`) |
| `c4builder --site -w` | то же с пересборкой на каждое сохранение и перезагрузкой браузера |
| `c4builder check <файлы...>` | проверяет диаграммы `.puml`, `.iuml`, `.d2`, `.bpmn` без сборки, код выхода 0 или 1 |
| `c4builder jre info` | какая Java будет использована (JSON) |
| `c4builder jre install [--force]` | скачать JRE в кэш заранее; `--force` — даже если есть системная Java |
| `c4builder --list` | показать текущий конфиг; с 0.5.0 вне проекта — ошибка с кодом 1, файлов не создаёт |
| `c4builder --reset` | очистить конфиг проекта; с 0.5.0 вне проекта — ошибка с кодом 1 |
| `c4builder --docs` | краткая справка по ключам конфига и адрес этой документации |

Позиционные команды — `check`, `jre`, `site`, а с 0.5.0 ещё `new` и `config`. С 0.5.0 любой
другой позиционный аргумент — ошибка `unknown command` с кодом 1: опечатка (`c4builder nwe`)
больше не запускает сборку.

Флаги:

| Флаг | Значение |
|---|---|
| `-c, --config-file <путь>` | другой файл конфига вместо `.c4builder` |
| `-w, --watch` | пересобирать при изменениях в исходниках и папках плагинов |
| `-o, --open` | открыть сайт в браузере (с `--site`) |
| `-p, --port <n>` | порт для `--site` (по умолчанию `webPort` из конфига, 3000) |
| `--system-fonts` | рендер системными шрифтами на один запуск |
| `-V, --version` | версия |

## Как читается конфиг

`.c4builder` — JSON в папке проекта. Первая сборка задаёт недостающие ключи через мастер и
ставит `hasRun: true`; после этого `c4builder` собирает без вопросов. `new -y` сразу пишет
полный конфиг, поэтому мастера не будет вовсе.

Ключи проверяются схемой. Значение не того типа останавливает сборку с ошибкой, где назван
ключ, а `c4builder --config` позволяет его исправить. Неизвестные ключи молча
отбрасываются — так старый c4builder не падает на конфиге от нового. Ключи функций, удалённых
из старых версий, дают предупреждение с их списком, сборка продолжается.

## Ключи `.c4builder`

| Ключ | По умолчанию | Что задаёт |
|---|---|---|
| `projectName` | имя при создании | имя проекта: заголовок сайта и единого файла |
| `homepageName` | `Overview` | заголовок корневой страницы |
| `rootFolder` | `src` | папка исходников |
| `distFolder` | `docs` | папка выхода, пересоздаётся при каждой сборке |
| `generateWEB` | `true` | сайт на docsify |
| `generateMD` | `true` | markdown по папкам |
| `generateCompleteMD` | `false` | один файл `<projectName>.md` |
| `generateLLMS` | `true` в новых проектах, выкл. без ключа | `llms.txt` и `llms-full.txt` для агентов, нужен `generateWEB` (с 0.5.0) |
| `includeTableOfContents` | `true` | дерево страниц вверху каждого markdown-файла |
| `includeNavigation` | `false` | ссылки на родителя и дочерние страницы в markdown |
| `includeBreadcrumbs` | `true` | путь страницы под заголовком |
| `diagramsOnTop` | `true` | диаграммы до текста страницы |
| `includeLinkToDiagram` | `false` | ссылка вместо картинки диаграммы |
| `embedDiagram` | `false` | картинка в markdown base64-строкой |
| `excludeOtherFiles` | `false` | не копировать прочие файлы из исходников |
| `generateLocalImages` | `true` | локальный рендер; `false` — ссылки на онлайн-сервер |
| `plantumlServerUrl` | `https://www.plantuml.com/plantuml` | сервер для `generateLocalImages: false` |
| `diagramFormat` | `svg` | `svg` или `png` |
| `d2Layout` | `dagre` | раскладка D2: `dagre` или `elk` |
| `useSystemFonts` | `false` | системные шрифты вместо вендорного |
| `charset` | `UTF-8` | кодировка исходников PlantUML |
| `webTheme` | `vendor/vue.css` | CSS-тема docsify |
| `supportSearch` | `true` | поиск в sidebar |
| `repoUrl` | пусто | ссылка на репозиторий в углу сайта |
| `executeScript` | `false` | выполнение `<script>` в страницах и подключение swagger-ui |
| `docsifyTemplate` | пусто | путь к модулю со своим шаблоном `index.html` |
| `webPort` | `3000` | порт `c4builder site` |
| `webFileName` | — | одно имя `.md` для всех страниц сайта вместо имени папки |
| `excludeSidebarFolderByPath` | — | список путей (от папки проекта, например `src/Архив`), скрытых из sidebar |
| `plugins` | `[]` | плагины сборки, см. [Плагины](06%20Плагины/06%20Плагины.md) |

Конфиг сайта этой документации — живой пример: `docs/ru/.c4builder` в репозитории.

## Свой шаблон docsify

`docsifyTemplate` указывает на ESM- или CommonJS-модуль, который экспортирует функцию.
Она получает объект настроек docsify (имя, sidebar, тема, поиск) и возвращает HTML для
`index.html`. Отправная точка — встроенный шаблон в `src/core/compose/docsify.template.ts`;
у этого сайта свой — `docs/docsify-template.mjs`.


## 06 Плагины

[Обзор](#C4-Builder)

# Плагины

Плагины добавляют в сборку содержимое извне `rootFolder` — виртуальные страницы — и
ресурсы сайта. Виртуальные страницы проходят обычный конвейер: sidebar, поиск, markdown по
папкам, единый файл, локальный рендер диаграмм.

Плагины перечисляются в `.c4builder` под ключом `plugins` — строкой `"имя"` или парой
`["имя", { ...опции }]`:

```json
{
  "plugins": [
    "openspec",
    ["openapi", { "dir": "../contracts", "glob": "*/openapi.yaml" }]
  ]
}
```

Идентификатор плагина разрешается в таком порядке: встроенное имя (`openspec`, `openapi`) →
локальный ESM-модуль (`./plugins/my.mjs`, `../shared/plugin.mjs`, абсолютный путь) → npm-пакет
из папки проекта.

- Опции проверяются схемой плагина **до** начала сборки. Встроенные плагины строгие:
  неизвестный ключ опций — ошибка.
- `${ENV_VAR}` в строковых опциях заменяется значением переменной окружения (не задана —
  пустая строка) и никогда не печатается. URL архивов попадают в сообщения без query-строки,
  поэтому токен в `?private_token=${TOKEN}` не утечёт в лог.
- Битая запись `plugins` всегда роняет сборку: это единственный ключ, который мастер не
  может починить.
- Старые версии c4builder ключ `plugins` игнорируют, так что откат версии не ломает сборку.

## `openspec` — журнал решений на сайте

Публикует [OpenSpec](https://github.com/Fission-AI/OpenSpec)-store как раздел сайта:
сводка (счётчики, прогресс задач), страница на каждый активный change, дерево спек и архив.
Раздел «Журнал решений» этого сайта собран именно так, из папки `openspec/` репозитория.

- Страница change'а показывает шапку (схема, даты, прогресс задач, ссылки на подстраницы) и
  первый артефакт из `artifacts` — по умолчанию `proposal`, чтобы «зачем» было видно без
  лишнего клика. Остальные артефакты (`design`, `tasks`, затем прочие `*.md` по алфавиту) —
  подстраницы, дельты спек — под `specs/…` с той же раскладкой папок.
- Блоки ```` ```plantuml ````, ```` ```puml ```` и ```` ```d2 ```` внутри артефактов рендерятся
  **локальными** движками, на plantuml.com ничего не уходит. Имя картинки считается от
  содержимого блока, так что вставка или перестановка блоков не подхватит чужую картинку из
  кэша.
- Блок, который не рендерится, не валит сборку: на странице будет заглушка, а сборка
  напечатает предупреждение с именем файла артефакта.
- Относительные ссылки между артефактами ведут на их страницы, файлы, на которые ссылаются
  артефакты (картинки, заметки), копируются рядом со страницей.
- В режиме `-w` папка store тоже отслеживается.

| Опция | По умолчанию | Значение |
|---|---|---|
| `dir` | `openspec` | папка store (от папки проекта) |
| `mount` | `OpenSpec` | название раздела и его путь в выходе |
| `artifacts` | `["proposal","design","tasks"]` | порядок артефактов; первый показывается на странице change'а |

## `openapi` — swagger-ui для набора спек

Находит спеки по `glob` в локальной папке (`dir`) **или** в архиве `tar.gz`/`zip`, скачанном
по HTTP (`archive` — например, URL архива репозитория GitLab или GitHub). На каждую спеку —
страница, названная по родительской папке спеки (для спек в корне источника — по имени
файла), плюс индекс.

- Все `yaml`/`yml`/`json` источника копируются в `<mount>/_specs/…` с исходной раскладкой,
  поэтому относительные `$ref` (в том числе на общие файлы схем, не попавшие в `glob`)
  продолжают работать.
- Страницы грузят swagger-ui из вендорных файлов: без CDN, без внешнего валидатора спек
  (бейдж `validator.swagger.io` выключен) и без доступа читателя к исходному репозиторию.
- Плагин сам включает `executeScript` (и пишет об этом в лог) и подключает `swagger-ui.css` и
  `swagger-ui-bundle.js` в `index.html`, так что свой `docsifyTemplate` править не нужно.
- Архив скачивается один раз за процесс, в режиме `-w` переиспользуется.
- За TLS-инспектирующим прокси скачивание падает с `self-signed certificate in certificate
  chain` — укажите CA-бандл в `NODE_EXTRA_CA_CERTS` (Node не читает ни системное хранилище,
  ни `SSL_CERT_FILE`). Сообщение об ошибке подсказывает это же.

| Опция | По умолчанию | Значение |
|---|---|---|
| `mount` | `API` | название раздела |
| `dir` | — | локальная папка со спеками (отслеживается в `-w`) |
| `archive` | — | HTTP(S)-URL архива tar.gz/zip |
| `subdir` | — | папка внутри архива или `dir` |
| `headers` | — | HTTP-заголовки запроса архива; пустые значения отбрасываются |
| `glob` | `**/openapi.{yaml,yml,json}` | шаблон спек (`**`, `*`, `?`, `{a,b}`); каталоги с точкой в начале имени не обходятся |

Пример: store OpenSpec лежит рядом с C4-исходниками, а контракты берутся из другого
репозитория. Пустой `GITLAB_TOKEN` отбросит заголовок, поэтому один и тот же конфиг работает
и с токеном, и без него:

```json
{
  "plugins": [
    "openspec",
    ["openapi", {
      "archive": "https://gitlab.example.com/api/v4/projects/123/repository/archive.tar.gz?sha=main",
      "glob": "*/openapi.yaml",
      "headers": { "PRIVATE-TOKEN": "${GITLAB_TOKEN}" }
    }]
  ]
}
```

## Свой плагин

Плагин — ESM-модуль, default-экспорт которого — обычный объект. Для типизации есть
`definePlugin` из `@alfacapital-tech/c4builder/dist/core/plugins/types.js`.

```js
import { z } from 'zod';
export default {
  name: 'changelog',
  options: z.object({ file: z.string().default('CHANGELOG.md') }).strict(), // необязательно
  watchPaths: (opts) => [opts.file],                                          // необязательно
  assets: { styles: ['/abs/path/x.css'], scripts: ['/abs/path/x.js'] },      // необязательно
  requires: { executeScript: true },                                          // необязательно
  async afterScan(ctx, opts) {
    // ctx.tree, ctx.options — дерево и опции сборки; ctx.source({ dir } | { archive, subdir, headers })
    // разрешает папку-источник; ctx.addPage добавляет виртуальную страницу
    // (недостающие родители станут индексными страницами).
    ctx.addPage({
      path: ['Changelog'],
      markdown: '## Latest\n\n![flow](flow.puml)',
      diagrams: [{ file: 'flow.puml', content: '@startuml\nA -> B\n@enduml' }]
    });
  },
  async afterBuild(ctx, opts) { /* ctx.distFolder, ctx.options — скопировать файлы, проверить выход */ }
};
```

Хуки вызываются в порядке списка `plugins`. Исключение в хуке прерывает сборку с именем
плагина, копия прошлого выхода при этом сохраняется. Путь виртуальной страницы не может
совпадать с реальной папкой исходников — сборка остановится с просьбой переименовать `mount`.


## 07 Docker и CI

[Обзор](#C4-Builder)

# Docker и CI

## Docker-образ

В образе есть всё для сборки: Node, JRE, PlantUML-jar, шрифты, D2 и BPMN-движок. Смонтируйте проект в
`/pwd`:

```bash
docker run --rm -v "$PWD:/pwd" ghcr.io/alfacapital-tech/c4builder:latest c4builder
```

Проверка диаграмм без установки чего-либо:

```bash
docker run --rm -v "$PWD:/pwd" ghcr.io/alfacapital-tech/c4builder:latest c4builder check src/context.puml
```

Теги образа синхронны с npm-тегами:

| Тег | Что это |
|---|---|
| `X.Y.Z`, `sha-…` | неизменяемые: конкретный релиз или коммит |
| `X.Y` | последний патч стабильной ветки |
| `latest` | последний стабильный релиз |
| `rc` | последний релиз-кандидат |
| `edge` | последний коммит в `master` |
| `pr-N` | сборки pull request'ов |

Для воспроизводимой сборки в CI закрепляйте `X.Y.Z`: другая версия PlantUML может сдвинуть
раскладку диаграмм.

## Сборка в CI

Образ можно взять образом job'а напрямую: `c4builder` лежит в `PATH`.

GitLab CI, проверка диаграмм и публикация в GitLab Pages (в `.c4builder` задан
`"distFolder": "public"`):

```yaml
check:
  image: ghcr.io/alfacapital-tech/c4builder:0.4.0
  script:
    - find src \( -name '*.puml' -o -name '*.d2' -o -name '*.bpmn' \) -exec c4builder check {} +

pages:
  image: ghcr.io/alfacapital-tech/c4builder:0.4.0
  script:
    - c4builder
  artifacts:
    paths: [public]
```

GitHub Actions без Docker: Node из `setup-node`, Java из `setup-java` (или пусть c4builder
скачает JRE сам):

```yaml
- uses: actions/setup-node@v4
  with: { node-version: 24 }
- uses: actions/setup-java@v4
  with: { distribution: temurin, java-version: 21 }
- run: npm i -g @alfacapital-tech/c4builder
- run: c4builder
```

Если Java на раннере нет, c4builder скачает JRE при первой сборке. Чтобы не качать её
каждый раз, кэшируйте каталог из `c4builder jre info` (поле `cacheDir`), а при промахе кэша
прогревайте его командой `c4builder jre install`.

Сборка ведёт себя в CI так же, как локально: код выхода не 0, если не собралась хотя бы одна
диаграмма. Отдельный быстрый шаг `c4builder check` на изменённых файлах даёт понятную ошибку
раньше полной сборки.

## Как собирается этот сайт

Workflow `.github/workflows/pages.yml` в репозитории c4builder: собирает CLI из того же
коммита, затем `docs/ru` и `docs/en` как два отдельных проекта, складывает их вместе с
лендингом в один артефакт и публикует в GitHub Pages только из `master`. На pull request'ах
сайт собирается, но не публикуется — битая диаграмма в документации видна до merge.


## 08 Агенты

[Обзор](#C4-Builder)

# Агенты

C4-модель в текстовом виде агент правит так же уверенно, как код: `Person`, `System`,
`Container` и `Rel` в `.puml` — это готовая семантическая модель, а не картинка. Не хватает
ему обычно другого: быстрого и однозначного ответа «сломал или нет». c4builder даёт его
локально, без сети и без человека.

## Цикл правка → check → сборка

1. **Правка.** Агент меняет `.md` и `.puml`/`.d2`/`.bpmn` в `src/` — добавляет контейнер, связь,
   страницу, шаг процесса.
2. **Проверка.** `c4builder check` на изменённых файлах:

   ```bash
   c4builder check "src/1 Internet Banking System/system.puml"
   ```

   Код выхода 0 — всё собирается. Код 1 — в выводе строка с файлом и номером строки:

   ```text
   ✗ src/1 Internet Banking System/system.puml: line 12: Fatal parsing error
   ```

   Проверка идёт тем же движком и с теми же `!include`, что и сборка, и занимает секунды:
   агент исправляет ошибку и повторяет, пока не получит 0. Для `.bpmn` каждое нарушение
   модели — строка с id элемента и правилом: `✗ <файл>: <id> [<правило>] <описание>`.
3. **Сборка.** `c4builder` собирает проект целиком; `c4builder --site -w` держит сайт
   открытым у человека и пересобирает его на каждое сохранение агента.

Полная сборка тоже завершается с кодом не 0, если не отрендерилась хотя бы одна диаграмма,
поэтому её можно ставить последним шагом агента или в CI.

## Почему офлайн-рендер важен для агентов

- **Нет сети — нет случайных отказов.** PlantUML-jar, C4-библиотека, шрифт, D2 и BPMN-движок
  лежат в пакете; сборка не зависит от plantuml.com, прокси и лимитов.
- **Один вход — один выход.** Вендорный шрифт и закреплённые версии движков дают
  одинаковые SVG на любой машине. Дифф в pull request показывает то, что агент изменил в
  модели, а не шум окружения.
- **Исходники не уходят наружу.** Архитектура часто содержит то, чему не место на чужом
  сервере; локальный рендер это исключает.

## Скиллы для агентов

c4builder поставляет [Agent Skills](https://agentskills.io) для Claude Code, Codex, Cursor и других
агентов, которые поддерживает утилита [`skills`](https://github.com/vercel-labs/skills). Скиллы
лежат в папке `skills/` репозитория (в npm-пакет не входят) и описывают последний стабильный
релиз, поэтому команды в них записаны флагами: `--new`, `--config`.

```bash
npx skills add AlfaCapital-Tech/C4-Builder/skills                    # оба скилла в текущий проект
npx skills add AlfaCapital-Tech/C4-Builder/skills --skill c4builder  # только один
```

`-g` ставит скиллы пользователю, а не в проект. Путь `/skills` в команде обязателен: без него
утилита подхватит ещё и служебные скиллы разработки самого c4builder из `.claude/skills/`.

| Скилл | Когда пригодится |
|---|---|
| `c4builder` | работа с проектом: раскладка `src/` и `.c4builder`, цикл правка → `c4builder check` → сборка, конвенции C4-PlantUML (stdlib-инклюды, общий `.iuml`, офлайн-рендер), D2, BPMN-процессы без координат, плагины `openspec` и `openapi`, `llms.txt` |
| `c4builder-setup` | установка и обновление (npm-каналы `latest` и `rc`, Docker-образ), Java или скачиваемая JRE, проверочная сборка шаблонного проекта |

## AGENTS.md в новом проекте

С версии 0.5.0 `c4builder --new` кладёт в проект `AGENTS.md`: команды сборки и проверки, порядок
работы, раскладку проекта, конвенции диаграмм и команду установки скиллов. Его читают Codex,
Cursor и Claude Code. Файл лежит рядом с `src/`, а не внутри, и в документацию не попадает.

## llms.txt: архитектура для чтения агентом

С `"generateLLMS": true` (с версии 0.5.0, нужен `generateWEB`) в корне сайта появляются два файла
по соглашению [llmstxt.org](https://llmstxt.org/):

- **`llms.txt`** — точка входа: имя проекта, краткое описание и плоский список страниц в порядке
  sidebar, вида `- [Система / Контейнер](Система/Контейнер/Контейнер.md)`. Папки из
  `excludeSidebarFolderByPath` в список не попадают, страницы плагинов (например, `openspec`)
  попадают. Ссылки — относительно корня сайта.
- **`llms-full.txt`** — полный текст всех страниц одним файлом, в том же порядке, что и единый
  markdown. Каждая диаграмма вставлена **исходником** в блоке `plantuml`, `d2` или `xml` (BPMN), а не картинкой —
  независимо от `diagramFormat`, `embedDiagram` и `includeLinkToDiagram`. Локальные `!include` и
  D2-импорты (вложенные тоже) приводятся один раз в приложении `## Included files` в конце;
  stdlib-инклюды `!include <C4/...>` и инклюды по URL остаются строками в исходнике.

Исходник полезнее картинки: текст C4-PlantUML (`Person`, `System`, `Rel`) — готовая модель, а SVG
по ссылке агенту ничего не даёт. Чтобы ответить на вопрос «от чего зависит сервис X», агенту
достаточно прочитать `llms-full.txt`, не обходя страницы.

Без сайта сборка печатает предупреждение и файлы не создаёт. В новых проектах ключ включён;
существующий `.c4builder` без ключа собирается как раньше — включите его через
`c4builder --config` или добавьте `"generateLLMS": true` в конфиг.

Файлы этого сайта:

| | Русская версия | English version |
|---|---|---|
| Оглавление | [ru/llms.txt](https://alfacapital-tech.github.io/C4-Builder/ru/llms.txt) | [en/llms.txt](https://alfacapital-tech.github.io/C4-Builder/en/llms.txt) |
| Полный текст | [ru/llms-full.txt](https://alfacapital-tech.github.io/C4-Builder/ru/llms-full.txt) | [en/llms-full.txt](https://alfacapital-tech.github.io/C4-Builder/en/llms-full.txt) |

## Подсказки для инструкций агента

В проекте, созданном до 0.5.0, `AGENTS.md` нет. Что стоит записать в `AGENTS.md` или `CLAUDE.md`
такого проекта:

- после правки диаграммы — `c4builder check <файл>`, исправлять до кода выхода 0;
- C4 подключать через stdlib (`!include <C4/C4_Container>`), общие стили — `!include ../styles.iuml`;
- новая страница — новая папка в `src/`, порядок — числовым префиксом;
- имена `.puml`, `.d2` и `.bpmn` в одной папке не должны совпадать без учёта расширения: выходной файл
  у них общий, и сборка остановится с ошибкой.

Плюс pre-commit-хук со страницы [Диаграммы](03%20Диаграммы/03%20Диаграммы.md): он не даст
закоммитить несобираемую диаграмму ни человеку, ни агенту.


## 09 Разработка

[Обзор](#C4-Builder)

# Разработка

Страница для тех, кто меняет сам c4builder. Репозиторий:
[AlfaCapital-Tech/C4-Builder](https://github.com/AlfaCapital-Tech/C4-Builder).

## Как устроен

```plantuml
@startuml
!include <C4/C4_Container>
!include ../styles.iuml

LAYOUT_TOP_DOWN()

Person(user, "Разработчик или агент", "Запускает CLI в каталоге проекта")

System_Boundary(c4b, "C4-Builder") {
    Container(cli, "CLI", "TypeScript, commander", "src/cli: разбор аргументов, мастер настройки, команды new, config, check, jre, site")
    Container(config, "Конфиг", "TypeScript, zod", "src/config: схема .c4builder, значения по умолчанию, опции сборки")
    Container(scan, "scan", "TypeScript", "src/core/scan: обход src/, дерево страниц и диаграмм")
    Container(plugins, "Плагины", "TypeScript", "src/core/plugins + src/plugins: хуки, виртуальные страницы; встроенные openspec и openapi")
    Container(render, "render", "TypeScript", "src/core/render: PlantUML через java, D2 через WASM, PNG через resvg, кэш по чексуммам")
    Container(compose, "compose", "TypeScript", "src/core/compose: страницы markdown, sidebar, index.html docsify")
    ContainerDb(vendor, "vendor/", "Файлы", "PlantUML jar, шрифты Nimbus Sans, docsify, swagger-ui")
}

System_Ext(java, "Java 17+", "Системная или скачанная c4builder JRE (Temurin)")
System_Ext(out, "Выход сборки", "dist: сайт, markdown, SVG/PNG")

Rel(user, cli, "Запускает")
Rel(cli, config, "Читает .c4builder")
Rel(cli, scan, "Запускает сборку")
Rel(scan, plugins, "afterScan: страницы плагинов")
Rel(scan, render, "Дерево")
Rel(render, compose, "Готовые диаграммы")
Rel(render, java, "Запускает PlantUML", "java -jar")
Rel(render, vendor, "jar, шрифт")
Rel(compose, out, "Пишет")
Rel(compose, vendor, "docsify")

SHOW_LEGEND()
@enduml
```

Сборка идёт фазами: **scan** обходит `src/` и строит дерево страниц, **плагины** добавляют
в него виртуальные страницы, **render** рендерит диаграммы (с кэшем по чексуммам), **compose**
пишет markdown, sidebar и `index.html`. CLI — тонкий слой поверх: разбор аргументов, мастер,
отдельные команды `check` и `jre`. Всё, что влияет на результат рендера (PlantUML-jar, шрифты,
docsify, swagger-ui), лежит в `vendor/` и руками не правится.

## Сборка и тесты

```bash
npm ci
npm run build          # tsc → dist/
npm test               # все тесты, включая golden
npm run test:unit      # без golden: быстро и без Java
npm run check          # biome: линт и формат
```

TypeScript, ESM, Node 22.17+. Тесты запускают собранный CLI из `dist/`, поэтому `npm test`
сначала компилирует.

**Язык вывода.** Всё, что CLI печатает пользователю, — на английском, комментарии в коде — на
русском. Тест `test/cli-language.test.mjs` падает на кириллице в строковых литералах `src/`.

**Golden-снапшоты.** `test/golden.test.mjs` собирает шаблон `template/src` в нескольких
конфигурациях и сравнивает весь выход с эталоном в `test/golden/` — побайтно, включая SVG.
Рендер закреплён на конкретной JRE (Temurin), которую тест скачивает в кэш сам. Изменили
рендер или шаблон — пересоберите эталоны `npm run test:golden:update` и приложите дифф
`test/golden/` к pull request'у. На некоторых дистрибутивах Linux SVG расходятся из-за
системного fontconfig; в CI на Ubuntu эталон стабилен.

**Сайт документации.** Исходники — `docs/ru/src` и `docs/en/src`, лендинг — `docs/landing`.
Тест `test/docs-parity.test.mjs` проверяет, что у RU и EN одинаковый набор страниц: папки
сопоставляются по числовому префиксу, файлы — по имени. Локальный просмотр:

```bash
npm run build
cd docs/ru && node ../../dist/index.js --site -w
```

## Процесс: OpenSpec

Изменения поведения сначала описываются в [OpenSpec](https://github.com/Fission-AI/OpenSpec):
`openspec/changes/<имя>/` — proposal (зачем), design (как и почему так), спеки (требования со
сценариями) и tasks. После реализации change архивируется, а его требования переходят в
`openspec/specs/`. Артефакты пишутся по-русски, код и идентификаторы — по-английски.

Весь store опубликован на этом сайте в разделе **Журнал решений**: активные change'и, спеки
и архив — офлайн-шаблон, отказ от Graphviz, локальный рендер D2 и PNG, переход на TypeScript, система
плагинов.

## Журнал изменений

Каждое пользовательское изменение (фича, исправление, поведение CLI) добавляет строку в
секцию `## Unreleased` файла
[CHANGELOG.md](https://github.com/AlfaCapital-Tech/C4-Builder/blob/master/CHANGELOG.md) в том же
pull request'е. Если меняется поведение, правится и страница этого сайта — в обеих языковых
версиях.

## Релизы

Публикацию запускает только пуш git-тега `v<версия>`. Merge в `master` ничего не публикует,
кроме Docker-тега `edge` и обновления этого сайта.

**Релиз-кандидат** — из `master`, сколько угодно раз; кто подписан на `rc`, получает каждый:

```bash
npm version X.Y.Z-rc.1 -m "rc: %s"      # первый кандидат
npm version prerelease -m "rc: %s"      # следующие: rc.2, rc.3, …
git push --follow-tags
```

Публикуется в npm-тег `rc` и Docker-тег `rc`; `latest` не меняется.

**Финальный релиз** — сначала переименовать `## Unreleased` в `## vX.Y.Z` в `CHANGELOG.md`:

```bash
npm version X.Y.Z -m "release: %s"
git push --follow-tags
```

Публикуется в npm-тег `latest` и Docker-теги `X.Y.Z`, `X.Y`, `latest`. npm публикуется через
OIDC (trusted publishing) с provenance, образ — в GHCR.


## Журнал решений

[Обзор](#C4-Builder)

**Active changes:** [0](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Changes/Changes) · **Specs:** [19](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/Specs) · **Archived:** [29](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/Archive) · **Tasks:** —

## Active changes

_No changes._

## Changes

[Обзор](#C4-Builder)

_No changes._

## Specs

[Обзор](#C4-Builder)

- [agent-skills](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/agent-skills/agent-skills)
- [bpmn-diagrams](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/bpmn-diagrams/bpmn-diagrams)
- [build-pipeline](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/build-pipeline/build-pipeline)
- [ci-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/ci-validation/ci-validation)
- [cli-commands](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/cli-commands/cli-commands)
- [config-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/config-validation/config-validation)
- [dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/dev-toolchain/dev-toolchain)
- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/diagram-rendering/diagram-rendering)
- [docs-site](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/docs-site/docs-site)
- [jre-resolution](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/jre-resolution/jre-resolution)
- [offline-site](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/offline-site/offline-site)
- [openapi-plugin](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/openapi-plugin/openapi-plugin)
- [openspec-plugin](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/openspec-plugin/openspec-plugin)
- [output-formats](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/output-formats/output-formats)
- [plugin-system](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/plugin-system/plugin-system)
- [project-scaffold](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/project-scaffold/project-scaffold)
- [project-template](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/project-template/project-template)
- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/regression-testing/regression-testing)
- [release-publishing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Specs/release-publishing/release-publishing)

## agent-skills

[Обзор](#C4-Builder)

# agent-skills Specification

## Purpose
Скиллы для coding-агентов (Claude Code, Codex, Cursor и др.), поставляемые вместе с c4builder: их состав, формат, способ установки и автоматическая проверка на соответствие реальному CLI.

## Requirements

### Requirement: Скиллы поставляются из репозитория в формате Agent Skills
Репозиторий SHALL содержать скиллы в каталоге `skills/<name>/SKILL.md` в формате Agent Skills, устанавливаемые командой `npx skills add AlfaCapital-Tech/C4-Builder/skills` (весь набор) или с `--skill <name>` (один скилл). Каталог `skills/` MUST NOT попадать в публикуемый npm-пакет.

#### Scenario: Скиллы находятся в стандартном месте
- **WHEN** просматривается дерево репозитория
- **THEN** каждый поставляемый скилл лежит в `skills/<name>/SKILL.md`, где `<name>` — имя скилла

#### Scenario: Скиллы не входят в npm-пакет
- **WHEN** выполняется `npm pack --dry-run`
- **THEN** в списке файлов пакета нет путей `skills/`

### Requirement: Состав набора скиллов
Набор SHALL включать два скилла:
- `c4builder` — работа с проектом c4builder: структура проекта и `.c4builder`, конвенции C4-PlantUML (stdlib-инклюды `<C4/...>`, общие `.iuml`, кириллица, офлайн-рендер), цикл «правка → `c4builder check` → сборка / `c4builder --site -w`», D2, встроенные плагины `openspec` и `openapi`;
- `c4builder-setup` — установка и диагностика: npm (каналы `latest` и `rc`) или Docker-образ, Node.js версии из `engines` в `package.json`, системная java или managed JRE (`c4builder jre install` / `jre info`), функциональная проверка сборкой шаблонного проекта.

Тексты скиллов MUST быть на английском языке.

#### Scenario: Общий скилл описывает цикл проверки
- **WHEN** агент загружает скилл `c4builder`
- **THEN** скилл предписывает после правки `.puml`/`.iuml`/`.d2` запускать `c4builder check <file...>` и исправлять ошибки по коду возврата и сообщению `file: line N`

#### Scenario: Скилл установки проверяет работоспособность, а не только версию
- **WHEN** агент выполняет скилл `c4builder-setup`
- **THEN** скилл завершается созданием проекта `c4builder --new --name <name> -y` во временном каталоге и его сборкой, а не только проверкой `c4builder --version`

### Requirement: Метаданные скилла валидны
Frontmatter каждого `SKILL.md` MUST содержать `name` и `description`. `name` MUST совпадать с именем каталога скилла, иметь длину 1–64 символа, состоять из `a-z`, `0-9` и `-`, не начинаться и не заканчиваться дефисом и не содержать `--`. `description` MUST быть непустым, не длиннее 1024 символов и описывать, что делает скилл и когда его применять. Проверка MUST выполняться автоматическими тестами на каждом прогоне CI.

#### Scenario: Имя скилла расходится с каталогом
- **WHEN** в `skills/c4builder/SKILL.md` указано `name: c4-builder`
- **THEN** тесты падают с сообщением, называющим файл и ожидаемое имя

#### Scenario: Пустое описание
- **WHEN** у скилла нет `description` или он пустой
- **THEN** тесты падают с сообщением, называющим файл

### Requirement: Скиллы ссылаются только на существующие команды CLI
Каждый флаг (`--x`, `-x`) и каждая подкоманда, упомянутые в командах `c4builder …` внутри скиллов и `template/AGENTS.md`, MUST существовать в CLI текущей версии: флаги — в выводе `c4builder --help`, подкоманды — в списке поддерживаемых позиционных подкоманд (`check`, `jre`, `site`, `new`, `config`). Проверка MUST выполняться автоматическими тестами против собранного `dist/`.

#### Scenario: Скилл упоминает несуществующий флаг
- **WHEN** в скилле есть команда `c4builder --serve`, а флага `--serve` в CLI нет
- **THEN** тесты падают с сообщением, называющим файл и неизвестный флаг

#### Scenario: Скилл упоминает неподдерживаемую подкоманду
- **WHEN** в скилле есть команда `c4builder serve`, а позиционной подкоманды `serve` в CLI нет
- **THEN** тесты падают с сообщением, называющим файл и подкоманду

### Requirement: Скиллы не содержат внутренней инфраструктуры
Скиллы и `template/AGENTS.md` MUST NOT содержать адреса внутренних хостов и приватных реестров организации; установка MUST описываться только через публичные источники (npm registry, GHCR). Проверка MUST выполняться автоматическими тестами.

#### Scenario: Внутренний хост в скилле
- **WHEN** в тексте скилла встречается адрес в домене `alfacapital.ru`
- **THEN** тесты падают с сообщением, называющим файл и найденный адрес

## bpmn-diagrams

[Обзор](#C4-Builder)

# bpmn-diagrams Specification

## Purpose
BPMN-диаграммы процессов как документация: агент пишет семантический BPMN 2.0 XML без координат, сборка валидирует его, раскладывает с горизонтальными пулами и дорожками и рендерит в стандартной нотации офлайн и детерминированно.

## Requirements

### Requirement: Источник BPMN — семантический XML без координат
Сборка SHALL принимать файлы `.bpmn` с BPMN 2.0 XML. Достаточно семантической части: процессы, collaboration с участниками (пулами), laneSet с дорожками, события, задачи, шлюзы, подпроцессы, sequence flow и message flow. Секция диаграммы (BPMN DI, `bpmndi:BPMNDiagram`) MUST NOT требоваться; если она присутствует, сборка MUST игнорировать её и раскладывать диаграмму автоматически. Невалидный XML или неизвестный BPMN-элемент MUST давать ошибку с путём файла и описанием причины.

#### Scenario: Файл без координат
- **WHEN** в проекте есть `.bpmn` только с семантической частью (без `bpmndi:BPMNDiagram`)
- **THEN** сборка рендерит диаграмму без ошибок

#### Scenario: Координаты в источнике игнорируются
- **WHEN** `.bpmn` содержит секцию BPMN DI с произвольными координатами
- **THEN** выход совпадает с выходом того же файла без секции DI

#### Scenario: Битый XML
- **WHEN** `.bpmn` не является корректным XML или ссылается на несуществующий id
- **THEN** сборка падает с сообщением, содержащим путь файла и причину (для висячей ссылки — её id)

### Requirement: Связи узлов выводятся из потоков
Сборка SHALL восстанавливать входящие и исходящие связи узлов по `sourceRef`/`targetRef` sequence flow до валидации и раскладки. Отсутствие элементов `incoming`/`outgoing` в источнике MUST NOT приводить к ошибкам валидации или к неверной раскладке.

#### Scenario: Потоки заданы только ссылками
- **WHEN** в `.bpmn` sequence flow заданы атрибутами `sourceRef`/`targetRef`, а у узлов нет `incoming`/`outgoing`
- **THEN** валидация не сообщает о несвязанных узлах, а диаграмма раскладывается с этими связями

### Requirement: Раскладка с горизонтальными пулами и дорожками
Сборка SHALL раскладывать диаграмму автоматически: пулы и дорожки — горизонтальные полосы с подписью слева, поток — слева направо, каждый узел — внутри полосы своей дорожки, message flow соединяют элементы разных пулов. Раскладка MUST быть детерминированной: один и тот же источник даёт одинаковые координаты. Если раскладка невозможна, сборка MUST завершаться ошибкой с путём файла и причиной, а не зависать или падать с трассой стека.

#### Scenario: Процесс с пулами и дорожками
- **WHEN** `.bpmn` содержит collaboration из двух пулов, у одного из них три дорожки, между пулами есть message flow
- **THEN** в SVG пулы и дорожки — горизонтальные полосы, узлы лежат в полосах своих дорожек, message flow соединяют пулы

#### Scenario: Ошибка раскладки
- **WHEN** движок раскладки не может разложить модель
- **THEN** сборка сообщает путь файла и причину, остальные диаграммы проекта не затронуты в отчёте об ошибке

### Requirement: Рендер в стандартной нотации без браузера
Сборка SHALL рендерить BPMN в SVG в стандартной нотации: маркеры событий (таймер, сообщение и др.), маркеры шлюзов, значки типов задач, пунктирные message flow. Рендер MUST выполняться локально, без браузера и без сетевых обращений. Метрики текста (перенос подписей, размеры) MUST вычисляться по вендорному шрифту независимо от режима системных шрифтов, чтобы повторный рендер одного источника давал байт-в-байт идентичный SVG. Идентификаторы внутри SVG MUST быть детерминированными. При `DIAGRAM_FORMAT=png` SVG растеризуется в PNG штатной растеризацией.

#### Scenario: Повторный рендер идентичен
- **WHEN** один и тот же `.bpmn` рендерится дважды, в том числе на разных машинах
- **THEN** SVG-выходы байт-в-байт совпадают

#### Scenario: Кириллица в подписях
- **WHEN** подписи задач, дорожек и пулов на русском
- **THEN** текст присутствует в SVG без искажений и переносится внутри фигур

#### Scenario: Сборка без сети
- **WHEN** сборка с `.bpmn` запускается в окружении без доступа в интернет
- **THEN** рендер завершается успешно

### Requirement: Семантическая валидация BPMN
Сборка SHALL валидировать каждую BPMN-модель фиксированным набором правил до раскладки. Набор MUST проверять как минимум: несвязанные узлы, отсутствие стартового или конечного события, узел вне дорожки или в нескольких дорожках (когда у процесса есть дорожки), sequence flow через границу пула, message flow внутри одного пула. Нарушение уровня error MUST прерывать рендер диаграммы с сообщением «путь файла, id элемента, правило, описание». Нарушение уровня warning MUST выводиться в лог без прерывания сборки.

#### Scenario: Узел без связей
- **WHEN** в процессе есть задача без входящих и исходящих потоков
- **THEN** рендер диаграммы прерывается с сообщением, содержащим путь файла, id задачи и имя правила

#### Scenario: Sequence flow между пулами
- **WHEN** sequence flow соединяет элементы разных пулов
- **THEN** валидация сообщает ошибку с id потока и подсказкой использовать message flow

#### Scenario: Узел вне дорожки
- **WHEN** у процесса есть дорожки, а узел не указан ни в одной из них
- **THEN** валидация сообщает ошибку с id узла

### Requirement: Проверка BPMN командой check
`c4builder check <file...>` SHALL принимать файлы `.bpmn` и выполнять для них те же разбор, валидацию, раскладку и рендер, что и сборка, без проекта и `.c4builder`. Код выхода MUST быть 0, только если все файлы прошли без ошибок; при ошибке — 1. Сообщения MUST содержать путь файла и, если известен, id элемента и имя правила. Предупреждения валидации MUST выводиться, но не влиять на код выхода.

#### Scenario: Ошибка валидации в check
- **WHEN** агент запускает `c4builder check process.bpmn` для модели с несвязанным узлом
- **THEN** команда печатает путь файла, id узла и правило и завершается с кодом 1

#### Scenario: Корректная модель
- **WHEN** `c4builder check process.bpmn` запускается для корректной модели
- **THEN** команда завершается с кодом 0

### Requirement: Зависимости BPMN опциональны и загружаются лениво
Пакеты BPMN-движка SHALL быть опциональными зависимостями. Они загружаются только при наличии в проекте (или в аргументах `check`) хотя бы одного `.bpmn`. При наличии `.bpmn` и отсутствии пакетов сборка MUST завершаться понятной ошибкой с указанием, как установить зависимости. После рендера ресурсы движка MUST освобождаться, чтобы процесс CLI завершался.

#### Scenario: Проект без BPMN
- **WHEN** в проекте нет `.bpmn`
- **THEN** пакеты BPMN-движка не загружаются, сборка и её выход не меняются

#### Scenario: .bpmn без установленных зависимостей
- **WHEN** в проекте есть `.bpmn`, а пакеты движка не установлены
- **THEN** сборка падает с понятным сообщением и подсказкой установки

### Requirement: Кэш BPMN-диаграмм учитывает версии движка
Чексумма кэша BPMN-диаграммы SHALL включать содержимое источника, формат вывода и версии пакетов раскладки, рендера и валидации. Смена любой из версий MUST приводить к перерисовке, а не к выдаче устаревшей картинки из кэша.

#### Scenario: Обновление пакета раскладки
- **WHEN** версия пакета раскладки изменилась, а источник — нет
- **THEN** при следующей сборке BPMN-диаграмма перерисовывается

## build-pipeline

[Обзор](#C4-Builder)

# build-pipeline Specification

## Purpose
Как устроен и собирается код CLI: TypeScript/ESM под `strict`, компиляция `tsc` в `dist/` без бандлера, запуск из собранного `dist/`, сохранение наблюдаемого поведения при порте и пофазная модульность ядра сборки (scan → render → compose).

## Requirements
### Requirement: Исходники на TypeScript и ESM

Исходный код CLI SHALL быть написан на TypeScript в модульной системе ESM.
Все модули под `src/` MUST иметь расширение `.ts`; `package.json` MUST
декларировать `"type": "module"`; модули MUST использовать `import`/`export`
(не `require`/`module.exports`) и лежать под `src/`, организованные по доменам
(`cli/`, `core/`, `config/`, `util/`). Компиляция MUST проходить в режиме
`strict` без ошибок.

#### Scenario: Модульный формат исходников
- **WHEN** просматривается любой модуль под `src/`
- **THEN** это `.ts`-файл с ESM-синтаксисом (`import`/`export`), а `package.json` содержит `"type": "module"`

#### Scenario: Строгая компиляция
- **WHEN** выполняется `npm run build`
- **THEN** `tsc` компилирует все модули `src/` в режиме `strict` без ошибок

#### Scenario: Ресурсы вне компиляции доступны из собранного кода
- **WHEN** собранный модуль обращается к вендорным ресурсам (`vendor/`) или шаблону (`template/`)
- **THEN** путь резолвится к корню пакета через `import.meta.url`, а не к каталогу внутри `dist/`, и рендер/скаффолд находят JAR, шрифты и шаблон

### Requirement: Компиляция tsc → dist/ без бандлера

Проект SHALL компилироваться `tsc` в каталог `dist/` без бандлера. `tsconfig.json`
MUST задавать `module`/`moduleResolution` `nodenext`, `outDir: dist`, `rootDir: src`.
Относительные импорты в исходниках MUST указывать расширение `.ts`
(`allowImportingTsExtensions`), а `tsc` MUST переписывать их в `.js` в эмите
(`rewriteRelativeImportExtensions`). `allowJs` MUST быть выключен: `.js`-модули
под `src/` не допускаются.

#### Scenario: Сборка порождает dist
- **WHEN** выполняется `npm run build`
- **THEN** `tsc` компилирует `src/**` в `dist/**` с расширениями `.js`, без бандлинга

#### Scenario: Расширения импортов переписываются
- **WHEN** исходный модуль содержит `import './render/diagram.ts'`
- **THEN** в соответствующем файле `dist/` импорт эмитится как `import './render/diagram.js'`

#### Scenario: Смесь .ts/.js запрещена
- **WHEN** под `src/` появляется `.js`-модуль
- **THEN** он не входит в компиляцию (`allowJs: false`) и сборка не может на него ссылаться

### Requirement: CLI запускается из собранного dist/

Опубликованный и локально собранный CLI SHALL исполняться из `dist/`. Поля `bin`
и `main` в `package.json` MUST указывать на `dist/index.js`; точка входа MUST
сохранять shebang `#!/usr/bin/env node`.

#### Scenario: Запуск собранного CLI
- **WHEN** после `npm run build` выполняется `node dist/index.js --help`
- **THEN** CLI выводит справку (эквивалентно запуску до порта)

#### Scenario: bin установленного пакета указывает на dist
- **WHEN** пакет установлен и вызвана команда `c4builder`
- **THEN** запускается `dist/index.js`

### Requirement: Порт сохраняет наблюдаемое поведение

Переход на TypeScript/ESM MUST NOT менять наблюдаемое поведение CLI: вывод сборки
(сайт/markdown, диаграммы), формат конфига `.c4builder` и совместимость с
конфигом потребителя MUST оставаться прежними. Golden-набор MUST проходить без
регенерации эталонов.

#### Scenario: Golden-паритет
- **WHEN** golden-набор прогоняется на собранном из `dist/` CLI
- **THEN** результат совпадает с эталонами без их обновления

### Requirement: Пофазная модульность ядра сборки

Ядро сборки SHALL быть организовано по фазам: скан дерева исходников
(`core/scan/`), рендер диаграмм (`core/render/`) и компоуз выводов
(`core/compose/`) MUST жить в отдельных модулях со своими экспортируемыми
типами границ. `core/build.ts` SHALL содержать только оркестрацию
(последовательность фаз, бэкап/восстановление выходного каталога, прогресс)
и MUST NOT содержать логику самих фаз.

#### Scenario: Фазы в отдельных модулях
- **WHEN** просматривается `src/core/`
- **THEN** построение дерева, рендер диаграмм и генерация markdown/сайта находятся в модулях `scan/`, `render/`, `compose/` соответственно, а не в `build.ts`

#### Scenario: Оркестратор без логики фаз
- **WHEN** просматривается `src/core/build.ts`
- **THEN** он импортирует фазы как модули и не содержит реализации скана, рендера или компоуза

#### Scenario: Дробление не меняет поведение
- **WHEN** golden-набор прогоняется после выделения фаз
- **THEN** результат совпадает с эталонами без их регенерации

## ci-validation

[Обзор](#C4-Builder)

# ci-validation

## Purpose

Требования к CI-проверке репозитория на GitHub Actions: автоматический прогон тестового набора на PR и push в master, красный статус при падении, отмена конкурентных прогонов ветки.
## Requirements
### Requirement: Тесты выполняются на каждый PR и push в master
Репозиторий SHALL содержать GitHub Actions workflow (`.github/workflows/ci.yml`), запускающий полный тестовый набор на события `pull_request` и `push` в `master`. Workflow MUST выполнять тесты на матрице Node.js 22 и 24, с установленной Java (Temurin), на пинованном образе раннера (`ubuntu-24.04`). Workflow MUST NOT устанавливать внешний graphviz — рендер диаграмм выполняется Java-движком Smetana.

#### Scenario: Открыт pull request
- **WHEN** открыт или обновлён PR
- **THEN** workflow устанавливает зависимости (`npm ci`) и запускает тесты на Node 22 и Node 24

#### Scenario: Push в master
- **WHEN** выполнен push в ветку master
- **THEN** workflow запускает тот же тестовый набор

#### Scenario: graphviz не устанавливается
- **WHEN** выполняется job workflow
- **THEN** среди шагов нет установки graphviz, а тесты рендера при этом проходят

### Requirement: Падение тестов даёт красный статус проверки
Неуспешное завершение любого теста MUST приводить к неуспешному завершению workflow и красному статусу проверки на PR.

#### Scenario: Тест упал в PR
- **WHEN** хотя бы один тест завершился с ошибкой
- **THEN** job завершается с ненулевым кодом и PR получает failed-статус проверки

### Requirement: Конкурентные прогоны одной ветки отменяются
Workflow MUST использовать `concurrency` с отменой предыдущего незавершённого прогона той же ветки (cancel-in-progress), чтобы не копить очередь на быстрых итерациях.

#### Scenario: Повторный push в ту же ветку PR
- **WHEN** в ветку PR приходит новый push до завершения предыдущего прогона
- **THEN** предыдущий прогон отменяется и запускается новый

### Requirement: Линт и формат проверяются на CI
Workflow CI SHALL содержать отдельную джобу `lint` (вне node-матрицы, без установки Java), выполняющую проверку линта и формата пинованной версией Biome (`biome ci`). Нарушение линта или формата MUST приводить к красному статусу проверки PR наравне с падением тестов.

#### Scenario: Нарушение формата в PR
- **WHEN** в PR попадает файл, не соответствующий сконфигурированному формату или правилам линта
- **THEN** джоба `lint` завершается с ненулевым кодом и PR получает failed-статус

#### Scenario: Линт не тянет тяжёлое окружение
- **WHEN** выполняется джоба `lint`
- **THEN** среди её шагов нет установки Java и запуска тестов — только checkout, setup-node, установка зависимостей и `biome ci`

### Requirement: Проект компилируется перед тестами

CI workflow MUST компилировать проект (`tsc`) до прогона тестов на каждой ноде матрицы, так как тесты исполняют собранный CLI из `dist/`. Ошибка компиляции MUST приводить к красному статусу проверки PR наравне с падением тестов и линта.

#### Scenario: Сборка перед тестами
- **WHEN** выполняется job тестовой матрицы (Node 22/24)
- **THEN** среди шагов присутствует сборка (`npm run build` / `tsc`) перед запуском тестов, и тесты исполняют CLI из `dist/`

#### Scenario: Ошибка компиляции в PR
- **WHEN** в PR попадает код, не компилируемый `tsc`
- **THEN** job завершается с ненулевым кодом и PR получает failed-статус проверки

## cli-commands

[Обзор](#C4-Builder)

# cli-commands Specification

## Purpose
Позиционные подкоманды CLI (`check`, `jre`, `site`, `new`, `config`) как синонимы флагов и отказ на неизвестную команду вместо молчаливой сборки.

## Requirements

### Requirement: Позиционные подкоманды CLI
CLI SHALL принимать позиционные подкоманды `check`, `jre`, `site`, `new` и `config`. `c4builder new` MUST вести себя так же, как `c4builder --new`, а `c4builder config` — как `c4builder --config`, включая сочетание с остальными флагами (`--name`, `-y`). Первый позиционный аргумент, не входящий в этот список, MUST приводить к сообщению об неизвестной команде со списком поддерживаемых и ненулевому коду возврата, без запуска сборки и без интерактивных вопросов.

#### Scenario: Позиционная команда создания проекта
- **WHEN** в пустом каталоге выполняется `c4builder new --name demo -y`
- **THEN** проект `demo` создаётся так же, как командой `c4builder --new --name demo -y`, процесс завершается с кодом 0

#### Scenario: Позиционная команда настройки
- **WHEN** в каталоге проекта выполняется `c4builder config`
- **THEN** запускается мастер настройки, как при `c4builder --config`

#### Scenario: Опечатка в команде
- **WHEN** выполняется `c4builder nwe`
- **THEN** печатается сообщение о неизвестной команде `nwe` со списком поддерживаемых, процесс завершается с ненулевым кодом, сборка не запускается

### Requirement: Формат вывода проверки диаграмм
`c4builder check <file...>` SHALL печатать результат по каждому файлу в стабильном англоязычном формате: успешный файл — `✓ <file>`, ошибочный — `✗ <file>: line <N>: <message>` для `.puml` (номер строки — от начала файла, начиная с 1), `✗ <file>: <message>` для `.iuml` (позиция относится к обёртке, номер не печатается). Сообщения об использовании команды без аргументов и о неподдерживаемом расширении MUST быть на английском. Код возврата MUST быть 0, если все файлы прошли проверку, и 1 иначе.

#### Scenario: Ошибка в диаграмме
- **WHEN** выполняется `c4builder check bad.puml`, где в строке 3 синтаксическая ошибка
- **THEN** в stderr печатается `✗ bad.puml: line 3: <сообщение движка>`, процесс завершается с кодом 1

#### Scenario: Неподдерживаемое расширение
- **WHEN** выполняется `c4builder check notes.txt`
- **THEN** печатается сообщение на английском о неподдерживаемом расширении со списком `.puml`, `.iuml`, `.d2`, процесс завершается с кодом 1

#### Scenario: Без аргументов
- **WHEN** выполняется `c4builder check` без файлов
- **THEN** печатается строка использования на английском, процесс завершается с кодом 1

### Requirement: Проверка библиотек .iuml с макросами C4
`c4builder check` SHALL проверять файл `.iuml` в контексте, где подключена стандартная библиотека C4-PlantUML (все уровни: контекст, контейнеры, компоненты, динамические и deployment-диаграммы): корректная библиотека, вызывающая макросы C4 (`UpdateElementStyle`, `Person`, `System` и т. п.), MUST проходить проверку. Библиотека без макросов C4 MUST проверяться с тем же результатом, что и раньше, а синтаксическая ошибка в `.iuml` MUST по-прежнему приводить к коду 1.

#### Scenario: Стили на макросах C4
- **WHEN** выполняется `c4builder check styles.iuml`, где файл содержит только `skinparam` и вызовы `UpdateElementStyle(...)`
- **THEN** печатается `✓ styles.iuml`, процесс завершается с кодом 0

#### Scenario: Библиотека без C4
- **WHEN** проверяется `.iuml` только со `skinparam` или объявлениями `participant`
- **THEN** проверка проходит, как и до изменения

#### Scenario: Битая библиотека
- **WHEN** в `.iuml` незакрытый вызов макроса
- **THEN** печатается `✗ <file>: <сообщение движка>`, процесс завершается с кодом 1

### Requirement: Справочные команды не создают файлов
Команды `c4builder --docs`, `c4builder --list` и `c4builder --reset` MUST NOT создавать `.c4builder`, `.c4builder.cache` или иные файлы в текущем каталоге. `--docs` SHALL работать в любом каталоге и завершаться с кодом 0. `--list` и `--reset` в каталоге без файла конфигурации SHALL печатать сообщение, что проект (`.c4builder`) не найден, и завершаться с ненулевым кодом; в каталоге проекта их поведение не меняется.

#### Scenario: Справка в пустой папке
- **WHEN** в пустом каталоге выполняется `c4builder --docs`
- **THEN** справка по ключам печатается, процесс завершается с кодом 0, каталог остаётся пустым

#### Scenario: Просмотр конфига вне проекта
- **WHEN** в пустом каталоге выполняется `c4builder --list`
- **THEN** печатается сообщение, что `.c4builder` не найден, процесс завершается с ненулевым кодом, каталог остаётся пустым

#### Scenario: Сброс вне проекта
- **WHEN** в пустом каталоге выполняется `c4builder --reset`
- **THEN** печатается сообщение, что `.c4builder` не найден, процесс завершается с ненулевым кодом, файлы не создаются

### Requirement: Язык пользовательского вывода CLI
Все сообщения, которые CLI выводит пользователю (stdout и stderr: ошибки, предупреждения, подсказки, прогресс сборки, вывод `--docs` и `--list`, сообщения валидации мастера настройки, тексты исключений, доходящие до пользователя), а также служебные тексты, которые сборка вставляет в выходы (заглушка вместо не отрендеренной диаграммы), SHALL быть на английском языке. Выбора языка вывода MUST NOT быть. Строковые литералы исходного кода CLI MUST NOT содержать кириллицу; комментарии в коде этим требованием не ограничены. Соблюдение MUST проверяться автоматическим тестом.

#### Scenario: Ошибка конфигурации на английском
- **WHEN** сборка запускается с `.c4builder`, где у ключа значение не того типа
- **THEN** сообщение об ошибке, перечисляющее невалидные ключи, напечатано на английском, процесс завершается с ненулевым кодом

#### Scenario: Предупреждение сборки на английском
- **WHEN** в `.c4builder` `generateLLMS: true`, а `generateWEB: false`
- **THEN** предупреждение о том, что `generateLLMS` требует `generateWEB`, напечатано на английском

#### Scenario: Валидация ответа мастера на английском
- **WHEN** в мастере `c4builder --config` пользователь оставляет имя проекта пустым
- **THEN** подсказка о недопустимом ответе выведена на английском

#### Scenario: Кириллица в строковом литерале
- **WHEN** в строковый литерал (обычный или шаблонный) в `src/` добавлен текст на кириллице
- **THEN** автоматический тест падает с сообщением, называющим файл и строку

#### Scenario: Кириллица в комментарии
- **WHEN** в `src/` есть комментарий на русском
- **THEN** тест на язык литералов не падает

## config-validation

[Обзор](#C4-Builder)

# config-validation Specification

## Purpose
Рантайм-валидация файла `.c4builder` при загрузке опций сборки: единая zod-схема
задаёт форму конфига (ключи, типы, дефолты), неполный/битый конфиг отклоняется
понятной ошибкой с ключом вместо молчаливых `undefined`-полей, а тип опций сборки
выводится из схемы, а не объявляется «оптимистично» полным.

## Requirements
### Requirement: Рантайм-валидация конфигурации при загрузке

`.c4builder` SHALL валидироваться по схеме при загрузке опций сборки. Значение
неверного типа MUST приводить к понятной ошибке, называющей проблемный ключ, а не
к молчаливому `undefined`-полю. Отсутствующие поля MUST заполняться значениями по
умолчанию — частичный или пустой конфиг остаётся валидным.

#### Scenario: Неверный тип значения отклоняется
- **WHEN** `.c4builder` содержит ключ со значением неверного типа (например, строка вместо булева)
- **THEN** загрузка завершается понятной ошибкой с указанием проблемного ключа, а не тихо продолжает с `undefined`-полем

#### Scenario: Частичный конфиг дополняется дефолтами
- **WHEN** `.c4builder` неполон или пуст (рукописный конфиг либо первый запуск)
- **THEN** отсутствующие поля берут значения по умолчанию и сборка продолжается

#### Scenario: Валидный конфиг не меняет поведение
- **WHEN** валидный `.c4builder` проходит валидацию
- **THEN** результирующие опции сборки совпадают с поведением до введения валидации (golden-эталоны без изменений)

### Requirement: Схема — единый источник формы конфига

Форма `.c4builder` (ключи, типы, значения по умолчанию) SHALL задаваться единой
схемой. Тип опций сборки MUST выводиться из этой схемы или проверяться ею, а не
объявляться «оптимистично» заведомо полным.

#### Scenario: Форма конфига определена в одном месте
- **WHEN** просматривается конфигурационный слой ядра
- **THEN** ключи, типы и дефолты `.c4builder` заданы одной схемой, на которую опирается загрузка опций сборки

## dev-toolchain

[Обзор](#C4-Builder)

# dev-toolchain Specification

## Purpose

Инструментальная планка качества кодовой базы: единый линтер и форматтер (Biome) с одной пинованной конфигурацией и npm-скриптами, явные зоны, свободные от обработки, ограниченный whitelist'ом состав npm-пакета и зафиксированная минимальная версия Node. Планка держится автоматически (локально и на CI), а не дисциплиной.

## Requirements

### Requirement: Единый линтер и форматтер
Репозиторий SHALL использовать Biome (пин точной версии в devDependencies) как единственный линтер и форматтер JS/TS/JSON-кода. Конфигурация `biome.json` MUST соответствовать существующему стилю кода (отступ 4 пробела, одинарные кавычки, точки с запятой, ширина строки ~110) и MUST покрывать исходники под `src/**/*.ts`, а линт MUST базироваться на наборе `recommended`; отключение правила или локальный `biome-ignore` MUST сопровождаться комментарием-причиной.

#### Scenario: Локальная проверка
- **WHEN** разработчик запускает `npm run lint` (или `npm run check`)
- **THEN** Biome проверяет линт и формат всех файлов вне ignore-зон (включая `src/**/*.ts`) и завершается ненулевым кодом при нарушениях

#### Scenario: Автоформатирование
- **WHEN** разработчик запускает `npm run format`
- **THEN** Biome приводит файлы к сконфигурированному стилю на месте

#### Scenario: Воспроизводимость версии
- **WHEN** линт/формат запускаются локально и в CI
- **THEN** используется одна и та же пинованная версия Biome и результат идентичен

### Requirement: Зоны, свободные от линта и форматирования
Конфигурация MUST исключать из обработки Biome: `vendor/` (сторонний код и шрифты), `template/` (пользовательский контент, он же исходники golden-fixture), `docs/`, `test/golden/` (эталоны), `test/.tmp/`, `node_modules/`. Форматирование этих зон MUST NOT происходить даже при `npm run format`.

#### Scenario: Эталоны и шаблон не переформатируются
- **WHEN** выполняется `npm run format` по всему репозиторию
- **THEN** файлы в `template/`, `vendor/`, `test/golden/` остаются байт-в-байт неизменными, golden-тест проходит без регенерации эталона

### Requirement: Состав npm-пакета ограничен whitelist'ом
`package.json` MUST содержать `files`-whitelist, включающий только собранный код CLI (`dist/`), `template/`, `vendor/`, README и лицензию. Служебные директории и исходники (openspec/, docs/, test/, `src/`, CI-конфиги, Dockerfile, tsconfig) MUST NOT попадать в публикуемый пакет. Опубликованный пакет MUST оставаться работоспособным: `c4builder --help` и `c4builder new` с шаблоном и вендорными ресурсами работают из установленного пакета.

#### Scenario: Проверка состава пакета
- **WHEN** выполняется `npm pack --dry-run`
- **THEN** в списке файлов пакета присутствуют `dist/`, `template/`, `vendor/`, README и отсутствуют openspec/, docs/, test/, `src/`, Dockerfile

#### Scenario: Smoke-проверка установленного пакета
- **WHEN** пакет из tarball устанавливается в чистую директорию и запускается `c4builder --help` и неинтерактивный `c4builder --new --name demo -y`
- **THEN** команды завершаются успешно, проект создаётся из шаблона

### Requirement: Минимальная поддерживаемая версия Node зафиксирована
`package.json` MUST декларировать `engines.node: ">=22.17"`. Код и рантайм-зависимости MUST NOT требовать возможностей Node, отсутствующих в 22.17; опциональные зависимости, загружаемые только для отдельных движков рендера, MUST быть совместимы с этой границей или давать понятную ошибку с требуемой версией Node.

#### Scenario: Установка на устаревшем Node
- **WHEN** пакет устанавливается на Node ниже 22.17 (в том числе Node 20)
- **THEN** npm сообщает о несовместимости engines (предупреждение, либо отказ при engine-strict)

#### Scenario: Работа на минимальной версии
- **WHEN** CLI запускается на Node 22.17
- **THEN** сборка шаблонного проекта и `c4builder check` выполняются без ошибок и без предупреждений об экспериментальных API Node

### Requirement: Рантайм-зависимости без известных уязвимостей

Рантайм-зависимости SHALL поддерживаться без известных уязвимостей уровня ≥ high.
CI MUST проверять это аудитом зависимостей и давать красный статус при регрессе,
чтобы новая уязвимость не проходила молча.

#### Scenario: Аудит зависимостей на CI
- **WHEN** выполняется CI
- **THEN** отдельная проверка аудита зависимостей проходит только при отсутствии известных уязвимостей уровня ≥ high

#### Scenario: Новая уязвимость ловится
- **WHEN** изменение зависимостей вносит известную уязвимость уровня ≥ high
- **THEN** проверка аудита падает с красным статусом, не пропуская регресс молча

## diagram-rendering

[Обзор](#C4-Builder)

# diagram-rendering

## Purpose

Требования к рендеру PlantUML-диаграмм при сборке: работа без внешнего graphviz (Java-движок раскладки Smetana), прямой вызов `java` с вендорным JAR в pipe-режиме и детерминированные метрики текста за счёт вендорного шрифта.

## Requirements

### Requirement: Диаграммы рендерятся без внешнего graphviz
Сборка SHALL рендерить PlantUML-диаграммы с использованием встроенного в PlantUML Java-движка раскладки (Smetana, `-Playout=smetana`) и MUST NOT требовать наличия внешнего graphviz/dot. Отсутствие или неработоспособность `dot` в системе MUST NOT приводить к ошибке рендера.

#### Scenario: Рендер при отсутствующем graphviz
- **WHEN** выполняется сборка, а исполняемый файл `dot` в системе недоступен
- **THEN** все диаграммы (C4 context/container/component/deployment/dynamic, class, sequence) успешно рендерятся в SVG, а кириллица в выходе сохраняется

#### Scenario: dot не вызывается
- **WHEN** запущен рендер диаграмм
- **THEN** процесс сборки не порождает вызовов внешнего `dot`

### Requirement: Рендер вызывает java напрямую
Сборка SHALL запускать PlantUML прямым вызовом Java с вендорным JAR, без посреднической
библиотеки `node-plantuml`. Исполняемый файл Java MUST определяться резолвером JRE
(см. capability `jre-resolution`: системная → кеш → публичный Adoptium), а не браться
безусловно как голая `java` из `PATH`. Источником данных MUST быть stdin/stdout
(pipe-режим), чтобы имя выходного файла определялось c4builder по имени `.puml`-файла,
а не по имени диаграммы из директивы `@startuml`.

#### Scenario: Имя выходного файла независимо от @startuml
- **WHEN** рендерится диаграмма, у которой в `@startuml <name>` задано имя, отличное от имени файла
- **THEN** выходной файл именуется по имени `.puml`-файла (как прежде), а не по `<name>`

#### Scenario: Локальные и stdlib-инклюды резолвятся
- **WHEN** рендерится диаграмма с `!include <C4/...>` (stdlib) и `!include ../styles.iuml` (локальный файл)
- **THEN** оба вида инклюдов резолвятся, диаграмма собирается корректно

#### Scenario: Java берётся из резолвера, а не голой из PATH
- **WHEN** годной системной java на `PATH` нет, но JRE доступен через кеш или скачивание
- **THEN** рендер использует резолвнутый бинарь Java и успешно рендерит диаграммы, а не
  падает с «java не найдена»

### Requirement: Детерминированные метрики текста через вендорный шрифт
Ширина текста в SVG зависит от метрик шрифта, поэтому сборка SHALL по умолчанию использовать шрифт Nimbus Sans, поставляемый в составе репозитория (`vendor/fonts/`), и задавать его как шрифт диаграмм по умолчанию. Шрифт MUST физически предоставляться JVM (а не только задаваться по имени), чтобы исключить молчаливый откат на системный шрифт. Пин действует, когда режим системных шрифтов выключен (`useSystemFonts=false`, значение по умолчанию).

#### Scenario: Рендер использует вендорный шрифт
- **WHEN** выполняется сборка на машине, где заданный шрифт не установлен системно
- **THEN** рендер использует шрифт из `vendor/fonts/`, а не системный fallback

#### Scenario: Повторяемость метрик
- **WHEN** одна и та же диаграмма рендерится дважды на одной машине
- **THEN** геометрия выходного SVG (координаты и `textLength`) байт-в-байт идентична

### Requirement: Режим системных шрифтов
Сборка SHALL поддерживать режим системных шрифтов: ключ `useSystemFonts`
(boolean, по умолчанию `false`) в `.c4builder` и CLI-флаг `--system-fonts`,
разово включающий режим независимо от конфига (флаг сильнее ключа). При
включённом режиме рендер MUST NOT передавать JVM шрифтовые аргументы
(`-Dsun.java2d.fontpath`, `-SdefaultFontName`, `-SCircledCharacterFontName`) —
PlantUML использует системный шрифт, как до вендорного пина. Ключ кеша рендера
MUST различать режимы шрифта: результат одного режима MUST NOT отдаваться из
кеша в другом. Вывод в этом режиме машинозависим — это ожидаемо и
детерминизм для него NOT гарантируется.

#### Scenario: Флаг включает системные шрифты поверх конфига
- **WHEN** в `.c4builder` ключ `useSystemFonts` отсутствует или равен `false`, но сборка запущена с `--system-fonts`
- **THEN** JVM запускается без шрифтовых аргументов, растеризатор использует системные шрифты

#### Scenario: Отсутствие ключа — прежнее поведение
- **WHEN** `.c4builder` не содержит ключ `useSystemFonts` (например, конфиг репо arch)
- **THEN** рендер идёт с вендорным шрифтом, поведение сборки не отличается от режима по умолчанию

#### Scenario: Кеш не смешивает режимы
- **WHEN** одна и та же диаграмма рендерится сначала в режиме по умолчанию, затем с `--system-fonts`
- **THEN** второй рендер не берёт результат первого из кеша (и наоборот)

#### Scenario: Golden-контур не зависит от режима
- **WHEN** выполняются golden-тесты
- **THEN** они рендерят вендорным шрифтом; режим системных шрифтов покрыт проверкой аргументов рендера, а не пиксельной сверкой

### Requirement: Второй бэкенд рендера выбирается по расширению
Сборка SHALL поддерживать `.d2`- и `.bpmn`-диаграммы наравне с `.puml` и выбирать движок
рендера по расширению файла: `.puml` — PlantUML, `.d2` — D2, `.bpmn` — BPMN-движок (см.
capability `bpmn-diagrams`). Добавление движков MUST NOT менять поведение существующих
`.puml`-проектов; выходной файл диаграммы именуется по имени исходного файла. Формат рендера
всех движков — SVG; при `DIAGRAM_FORMAT=png` SVG растеризуется в PNG отдельной стадией (см.
требование о PNG-выводе).

#### Scenario: Смешанное дерево .puml и .d2
- **WHEN** в дереве проекта присутствуют и `.puml`, и `.d2` файлы
- **THEN** `.puml` рендерятся PlantUML, `.d2` рендерятся D2, при формате по умолчанию
  (svg) оба дают SVG рядом с прочими выходами, ссылки в markdown работают для обоих

#### Scenario: BPMN рядом с другими движками
- **WHEN** в дереве проекта присутствуют `.puml`, `.d2` и `.bpmn` файлы
- **THEN** каждый файл рендерится своим движком, `.bpmn` даёт SVG (или PNG при
  `DIAGRAM_FORMAT=png`) с именем по исходному файлу, ссылки в markdown работают для всех

#### Scenario: Проект только из .puml не затронут
- **WHEN** в проекте нет ни одного `.d2`- и `.bpmn`-файла
- **THEN** сборка и её выход идентичны прежнему поведению, а зависимости D2 и BPMN не
  загружаются

### Requirement: Импорты D2 резолвятся через виртуальную файловую систему
D2-рендерер SHALL собирать граф импортов (`@`/`...@`) исходного `.d2`-файла и
передавать движку виртуальную файловую систему (`compile({ fs, inputPath })`), чтобы
переиспользуемые стили и определения из отдельных `.d2`-файлов применялись. Тот же
граф импортов MUST учитываться в чексумме кэша диаграмм: правка импортируемого файла
инвалидирует зависимые диаграммы.

#### Scenario: Общие стили через импорт
- **WHEN** `.d2`-диаграмма импортирует общий файл (`...@c4lib`) с classes/vars
- **THEN** импортируемые стили применяются в выходном SVG

#### Scenario: Правка импортируемого файла инвалидирует кэш
- **WHEN** изменён импортируемый `.d2`-файл, а сама диаграмма — нет
- **THEN** при следующей сборке зависимая диаграмма перерисовывается, а не берётся из кэша

### Requirement: Зависимость D2 опциональна и загружается лениво
Пакет движка D2 SHALL быть опциональной зависимостью и загружаться только при
наличии в проекте хотя бы одного `.d2`-файла. При наличии `.d2` и отсутствии пакета
сборка MUST завершаться понятной ошибкой с указанием, как установить зависимость.
После завершения рендера D2 ресурсы движка (webworker) MUST освобождаться, чтобы
процесс сборки корректно завершался.

#### Scenario: .d2 без установленного движка
- **WHEN** в проекте есть `.d2`, но пакет движка D2 не установлен
- **THEN** сборка падает с понятным сообщением и подсказкой установки, а не с
  невнятной ошибкой модуля

#### Scenario: Процесс завершается после сборки
- **WHEN** сборка с `.d2`-диаграммами завершена
- **THEN** CLI-процесс завершается и не остаётся висеть из-за незакрытого воркера

### Requirement: Единственный вендорный PlantUML JAR
Репозиторий SHALL поставлять ровно один PlantUML-JAR, и сборка MUST рендерить
PlantUML-диаграммы именно им, без выбора версии. Механизм выбора версии PlantUML
(список версий, опция и промпты) MUST отсутствовать.

#### Scenario: Рендер единственным JAR
- **WHEN** выполняется сборка PlantUML-диаграмм
- **THEN** используется единственный вендорный JAR, а какой-либо выбор версии не производится

#### Scenario: Нет промпта версии
- **WHEN** запускается создание проекта или мастер настройки
- **THEN** вопрос о версии PlantUML не задаётся

### Requirement: Легаси-ключ версии в конфиге игнорируется
Ключ `plantumlVersion` в существующем `.c4builder` SHALL игнорироваться: сборка всегда
использует единственный вендорный JAR. Если ключ задан конкретной версией, отличной от
`latest` и от версии вендорного JAR, сборка MUST напечатать однократное предупреждение,
что выбор версии удалён и используется вендорный JAR (ключ можно убрать), и продолжиться.
На значении `latest`, на версии вендорного JAR или при отсутствии ключа предупреждение
MUST NOT печататься. Сборка MUST NOT падать из-за этого ключа и MUST NOT изменять конфиг.

#### Scenario: Пин устаревшей версии
- **WHEN** в `.c4builder` `plantumlVersion` пинует удалённую версию (напр. `1.2021.7`)
- **THEN** печатается однократное предупреждение, сборка идёт единственным JAR, exit 0, конфиг не изменён

#### Scenario: latest или текущая версия — тихо
- **WHEN** `plantumlVersion` равен `latest`, версии вендорного JAR либо отсутствует
- **THEN** предупреждение не печатается, сборка идёт единственным JAR

### Requirement: PNG-вывод формируется растеризацией SVG
При `DIAGRAM_FORMAT=png` сборка SHALL получать PNG растеризацией SVG-выхода движка
(PlantUML или D2), а не нативным PNG-рендером. Не-ditaa диаграммы обоих движков
MUST рендериться в SVG и затем растеризоваться в PNG единым растеризатором. Растеризатор
MUST работать без браузера и без внешнего graphviz/dot. ditaa-диаграммы MUST оставаться
нативным PlantUML-PNG (у них нет SVG-представления) и MUST NOT проходить через растеризатор.

#### Scenario: PNG для PlantUML-диаграммы
- **WHEN** `DIAGRAM_FORMAT=png` и рендерится обычная (не-ditaa) `.puml`-диаграмма
- **THEN** PlantUML рендерит её в SVG, SVG растеризуется в PNG, выходной файл — `<имя>.png`

#### Scenario: PNG для D2-диаграммы
- **WHEN** `DIAGRAM_FORMAT=png` и рендерится `.d2`-диаграмма
- **THEN** D2 рендерит её в SVG, SVG растеризуется в PNG (раньше `.d2` при `png` оставались SVG)

#### Scenario: ditaa не растеризуется
- **WHEN** `DIAGRAM_FORMAT=png` и в проекте есть ditaa-диаграмма
- **THEN** ditaa рендерится нативным PlantUML-PNG без прохода через растеризатор, а её выход байт-в-байт совпадает с прежним

#### Scenario: SVG-формат не задействует растеризатор
- **WHEN** `DIAGRAM_FORMAT=svg`
- **THEN** диаграммы отдаются как SVG, растеризатор не вызывается и его зависимость не загружается

### Requirement: Детерминированная растеризация PNG с вендорным шрифтом
Растеризатор SVG→PNG SHALL в режиме по умолчанию (`useSystemFonts=false`)
использовать шрифт из состава репозитория (`vendor/fonts/`) и MUST NOT подгружать
системные шрифты, чтобы текст (включая кириллицу) рендерился одинаково независимо
от машины. Повторная растеризация одного SVG на одной версии растеризатора MUST
давать байт-в-байт идентичный PNG. В режиме системных шрифтов растеризатор SHALL
загружать системные шрифты и MUST NOT навязывать вендорное семейство.

#### Scenario: Кириллица в PNG
- **WHEN** диаграмма с кириллическим текстом растеризуется в PNG
- **THEN** кириллица корректно отрисована шрифтом из `vendor/fonts/`, а не системным fallback

#### Scenario: Повторяемость PNG
- **WHEN** один и тот же SVG растеризуется дважды на одной машине
- **THEN** оба PNG байт-в-байт идентичны

#### Scenario: PNG в режиме системных шрифтов
- **WHEN** растеризация выполняется при включённом `useSystemFonts`
- **THEN** растеризатор загружает системные шрифты, вендорное семейство не задаётся

### Requirement: Зависимость растеризатора загружается лениво
Пакет растеризатора SHALL загружаться только когда в проекте реально требуется PNG
(есть хотя бы одна не-ditaa диаграмма и `DIAGRAM_FORMAT=png`). При отсутствии пакета
в такой ситуации сборка MUST завершаться понятной ошибкой с подсказкой установки.

#### Scenario: PNG нужен, пакет не установлен
- **WHEN** `DIAGRAM_FORMAT=png`, есть не-ditaa диаграммы, но пакет растеризатора не установлен
- **THEN** сборка падает с понятным сообщением и подсказкой установки, а не с невнятной ошибкой модуля

#### Scenario: Растеризатор не нужен — не грузится
- **WHEN** формат SVG либо все диаграммы ditaa
- **THEN** пакет растеризатора не загружается

## docs-site

[Обзор](#C4-Builder)

# docs-site Specification

## Purpose
Публичный сайт документации C4-Builder: собирается самим c4builder из исходников
репозитория, существует на русском и английском с одинаковой структурой, имеет лендинг
и публикуется в GitHub Pages из CI. README и `c4builder --docs` ведут на этот сайт.

## Requirements

### Requirement: Сайт собирается c4builder из того же коммита
Сайт документации SHALL собираться CLI c4builder, скомпилированным из того же коммита
репозитория, а не опубликованной версией пакета. Сборка MUST выполняться в CI на каждый
pull request и на каждый push в `master`. Ошибка сборки любой языковой версии, включая
ошибку рендера диаграммы, MUST давать красный статус проверки.

#### Scenario: Сборка на pull request
- **WHEN** открыт pull request, меняющий исходники сайта или код CLI
- **THEN** CI собирает обе языковые версии сайта текущим кодом CLI и не публикует результат

#### Scenario: Битая диаграмма в исходниках сайта
- **WHEN** в исходниках сайта есть `.puml`, который не компилируется
- **THEN** проверка сборки сайта завершается красным статусом

### Requirement: Публикация только из master
Сайт SHALL публиковаться в GitHub Pages только по push в `master` (или ручному запуску
workflow на `master`). Pull request'ы и другие ветки MUST NOT менять опубликованный сайт.

#### Scenario: Merge в master
- **WHEN** изменения слиты в `master` и сборка сайта прошла
- **THEN** опубликованный сайт обновляется до состояния этого коммита

#### Scenario: Pull request
- **WHEN** CI отработал на pull request
- **THEN** опубликованный сайт остаётся прежним

### Requirement: Раскладка публикации
Опубликованный сайт SHALL содержать в корне лендинг на русском (`index.html`) и его
английскую версию (`en.html`), документацию на русском под `ru/` и на английском под
`en/`. Каждая страница лендинга MUST ссылаться на обе языковые версии документации и на
другую языковую версию лендинга. Лендинг и сайт документации MUST NOT загружать ресурсы
с внешних CDN: все скрипты, стили и шрифты отдаются с самого сайта.

#### Scenario: Корень сайта
- **WHEN** пользователь открывает корень опубликованного сайта
- **THEN** он видит русский лендинг со ссылками на `ru/`, `en/` и `en.html`

#### Scenario: Нет внешних ресурсов
- **WHEN** лендинг или страница документации загружаются в браузере
- **THEN** все запросы скриптов, стилей и шрифтов идут на домен сайта

### Requirement: Паритет структуры RU и EN
Исходники русской и английской документации SHALL иметь одинаковую структуру: каждой
папке-странице одной версии MUST соответствовать папка с тем же числовым префиксом
порядка на том же уровне в другой версии, а набор имён `.md`, `.puml` и `.d2` файлов в
соответствующих папках MUST совпадать. Расхождение MUST давать красный статус CI с
перечнем путей без пары.

#### Scenario: Страница добавлена только в одну версию
- **WHEN** в русской документации добавлена папка-страница без английской пары
- **THEN** CI падает и называет путь страницы без пары

#### Scenario: Структура совпадает
- **WHEN** обе версии содержат одинаковые по порядку папки и одинаковые имена файлов
- **THEN** проверка паритета проходит, независимо от различий в названиях папок

### Requirement: Журнал решений на сайте
Обе языковые версии сайта SHALL содержать раздел с OpenSpec-store репозитория (активные
change'и, спеки, архив), собранный встроенным плагином `openspec`. Английская версия MUST
предупреждать, что артефакты раздела написаны на русском.

#### Scenario: Новый change в репозитории
- **WHEN** в `openspec/changes/` слит новый change и сайт пересобран
- **THEN** change виден в разделе журнала решений обеих языковых версий

### Requirement: README как точка входа
`README.MD` SHALL содержать краткое описание проекта, отличия от upstream, quickstart и
ссылки на обе языковые версии сайта, не более 150 строк. Справочник по командам, конфигу,
выводам и плагинам MUST находиться на сайте, а не в README. README MUST NOT ссылаться на
файлы, отсутствующие в репозитории.

#### Scenario: Читатель на GitHub или npm
- **WHEN** пользователь открывает README на странице репозитория или пакета
- **THEN** он видит quickstart и ссылки на русскую и английскую документацию, без битых картинок

### Requirement: Журнал изменений в отдельном файле
История изменений SHALL вестись в `CHANGELOG.md` в корне репозитория: секция
`## Unreleased` сверху, далее версии `## vX.Y.Z` от новых к старым. README MUST NOT
содержать журнал изменений.

#### Scenario: Пользовательское изменение в PR
- **WHEN** PR меняет поведение CLI
- **THEN** строка об изменении добавляется в `## Unreleased` файла `CHANGELOG.md`

### Requirement: Ссылки на документацию ведут на сайт форка
`c4builder --docs` и `readme.md` шаблона `c4builder new` SHALL ссылаться на сайт
документации форка. Ссылки на сайт upstream (`adrianvlupu.github.io`) MUST отсутствовать
в коде CLI, шаблоне и README. Благодарности upstream и ссылки на исторические PR в
`CHANGELOG.md` допустимы.

#### Scenario: Справка CLI
- **WHEN** пользователь запускает `c4builder --docs`
- **THEN** в выводе указан адрес сайта документации форка

## jre-resolution

[Обзор](#C4-Builder)

# jre-resolution

## Purpose

Определение исполняемого файла Java для рендеринга PlantUML: приоритетная цепочка
источников (системная java → локальный кеш → публичный Adoptium), годность системной
java по мажорной версии, автоскачивание Temurin 21 JRE с проверкой целостности,
кеширование и переиспользование, ленивый резолв с командой прогрева и понятная ошибка
при провале.

## Requirements
### Requirement: Исполняемый файл Java резолвится по приоритетной цепочке
Сборка SHALL определять исполняемый файл Java по приоритетной цепочке источников:
(1) системная java (`JAVA_HOME`, затем `PATH`); (2) ранее скачанный JRE в локальном
кеше; (3) автоскачивание с публичного Adoptium. Первый годный источник MUST
использоваться, а последующие MUST NOT проверяться. Резолв MUST выполняться один раз за
сборку, а не на каждую диаграмму.

#### Scenario: Годная системная java — сеть не задействуется
- **WHEN** в системе есть годная java, а в проекте есть PlantUML-диаграммы
- **THEN** используется системная java, кеш и сеть не задействуются

#### Scenario: Системной нет, но JRE в кеше
- **WHEN** годной системной java нет, но в кеше есть ранее скачанный JRE
- **THEN** используется JRE из кеша, скачивание не выполняется

#### Scenario: Нет ни системной, ни кеша
- **WHEN** нет годной системной java и кеш пуст
- **THEN** выполняется скачивание JRE с публичного Adoptium

### Requirement: Годность системной java определяется мажорной версией
Системная java SHALL приниматься, если её мажорная версия ≥ 17 (определяется через
`java -version`). При меньшей версии система MUST считаться негодной, а резолвер MUST
переходить к следующему источнику. Отсутствие java или ошибка её запуска MUST NOT
прерывать сборку, а MUST вести к переходу на следующий источник цепочки.

#### Scenario: java 17+ принимается
- **WHEN** системная `java -version` сообщает мажорную версию ≥ 17
- **THEN** эта java используется для рендера

#### Scenario: Слишком старая java отвергается
- **WHEN** системная java имеет мажорную версию меньше 17
- **THEN** она не используется, резолвер переходит к кешу/скачиванию

#### Scenario: java не найдена — не падаем
- **WHEN** `java` отсутствует на `PATH` и `JAVA_HOME` не задан
- **THEN** резолвер не прерывается ошибкой, а переходит к следующему источнику

### Requirement: Автоскачивание Temurin 21 JRE с проверкой целостности
При необходимости скачивания сборка SHALL получать JRE **Temurin 21** (`image_type=jre`,
`vendor=eclipse`, hotspot) с публичного Adoptium под текущие ОС и архитектуру
(из `process.platform`/`process.arch`). Ссылка на архив и его контрольная сумма MUST
браться из Adoptium assets API; скачанный архив MUST проверяться по `sha256` до
распаковки; несовпадение MUST прерывать установку с ошибкой и не заполнять кеш.
Корпоративные/приватные зеркала как источник MUST NOT вводиться.

#### Scenario: Скачивание под текущую платформу
- **WHEN** выполняется скачивание JRE
- **THEN** `process.platform`/`process.arch` отображаются в параметры Adoptium
  (`os`/`arch`), и запрашивается архив под эту платформу

#### Scenario: Контрольная сумма совпала
- **WHEN** архив скачан и его `sha256` совпадает с суммой из assets API
- **THEN** архив распаковывается в кеш и используется

#### Scenario: Контрольная сумма не совпала
- **WHEN** `sha256` скачанного архива не совпадает с ожидаемым
- **THEN** установка прерывается ошибкой, кеш не заполняется

### Requirement: Скачанный JRE кешируется и переиспользуется
Скачанный и распакованный JRE SHALL храниться в пользовательском кеше под ключом
«версия + ОС + архитектура» и переиспользоваться последующими сборками без повторного
скачивания. Установка MUST считаться валидной только при наличии исполняемого
`bin/java` (`bin\java.exe` на Windows); неполная/битая установка MUST перекачиваться.

#### Scenario: Повторный запуск берёт JRE из кеша
- **WHEN** JRE уже скачан в кеш, запускается новая сборка без годной системной java
- **THEN** используется JRE из кеша, повторного скачивания и обращения к сети нет

#### Scenario: Битая установка перекачивается
- **WHEN** каталог кеша есть, но исполняемого `bin/java` в нём нет
- **THEN** установка считается невалидной и JRE скачивается заново

### Requirement: Резолв JRE ленивый и доступен командой прогрева
Резолв JRE SHALL выполняться лениво — только если в дереве проекта есть хотя бы одна
PlantUML-диаграмма (`.puml`). Проект без PlantUML-диаграмм (например, целиком на D2)
MUST NOT инициировать резолв или скачивание JRE. Дополнительно CLI SHALL предоставлять
команду прогрева (`c4builder jre install`), которая резолвит/скачивает JRE заранее (для
CI/офлайн) без запуска полной сборки.

#### Scenario: Проект без PlantUML не трогает java
- **WHEN** в проекте нет ни одного `.puml`-файла (например, только `.d2`)
- **THEN** резолв java не выполняется и JRE не скачивается

#### Scenario: Прогрев кеша командой
- **WHEN** выполняется `c4builder jre install` на машине без годной системной java
- **THEN** JRE скачивается и оказывается в кеше готовым, полная сборка не запускается

### Requirement: Понятная ошибка при невозможности резолва
Сборка SHALL завершаться понятной ошибкой, если ни один источник цепочки не дал рабочей
java (нет годной системной, кеш пуст, скачивание не удалось). Сообщение об ошибке MUST
указывать на два действия: установить JRE 17+ или запустить `c4builder jre install`, и
MUST NOT быть невнятным стектрейсом от `spawn`.

#### Scenario: Офлайн без java и кеша
- **WHEN** нет годной системной java, кеш пуст, а скачивание недоступно (нет сети)
- **THEN** сборка завершается понятным сообщением с подсказкой поставить JRE 17+ или
  запустить `c4builder jre install`, а не сырой ошибкой запуска процесса

## offline-site

[Обзор](#C4-Builder)

# offline-site Specification

## Purpose
Сайт, собранный c4builder, открывается и работает без интернета и ничего не отправляет за
пределы своего адреса: ни шрифты, ни emoji, ни исходники диаграмм не уходят на внешние сервисы.

## Requirements

### Requirement: Сайт по умолчанию не обращается к внешним доменам
Собранный docsify-сайт при встроенном шаблоне и теме по умолчанию (`webTheme: vendor/vue.css`) MUST NOT содержать в `index.html`, подключаемых CSS и сгенерированных страницах ссылок на ресурсы внешних доменов (`http://`, `https://`, `//host`), загружаемых браузером автоматически: шрифты, стили, скрипты, изображения. Встроенный шаблон MUST NOT подключать клиентский рендер PlantUML и MUST включать отображение emoji родными символами вместо картинок. Ссылки, которые пользователь сам написал в тексте страниц (обычные гиперссылки), этим требованием не затрагиваются.

#### Scenario: Шаблонный проект без внешних ресурсов
- **WHEN** проект создан `c4builder --new --name demo -y` и собран `c4builder`
- **THEN** в `index.html`, `vendor/*.css` и `.md`-страницах выхода нет адресов внешних доменов, кроме гиперссылок из исходного текста

#### Scenario: Тема без внешних шрифтов
- **WHEN** сайт собран с `webTheme: vendor/vue.css`
- **THEN** скопированный в выход `vendor/vue.css` не содержит `@import` внешних шрифтов, а вендорный файл пакета не изменён

#### Scenario: Emoji без картинок
- **WHEN** страница содержит `:smile:`
- **THEN** сайт показывает символ emoji, не запрашивая изображений с внешних адресов

#### Scenario: Совместимость пользовательского шаблона
- **WHEN** пользовательский `docsifyTemplate` подключает `vendor/docsify-plantuml.min.js`
- **THEN** файл присутствует в выходе (нет 404), сборка проходит, а опции шаблона содержат включённые родные emoji

### Requirement: Блоки PlantUML в страницах рендерятся при сборке
Fenced-блоки с языком `plantuml` в markdown-страницах проекта SHALL извлекаться в диаграммы страницы и рендериться тем же движком и в том же `diagramFormat`, что и файлы `.puml`; на месте блока MUST стоять изображение, а исходный текст блока MUST NOT оставаться в выходах (сайт, markdown, complete-markdown), чтобы клиентский рендер в браузере не мог его отправить. Блоки с другими языками (`puml`, `d2`, прочие) MUST оставаться кодом без изменений. Синтаксическая ошибка в блоке MUST NOT ронять сборку: на месте блока — заглушка, в логе — предупреждение с именем исходного файла.

#### Scenario: Блок plantuml становится картинкой
- **WHEN** `src/README.md` содержит блок ```` ```plantuml ```` с C4-диаграммой на stdlib
- **THEN** в выходах на его месте изображение, отрендеренное локально, и нет текста блока

#### Scenario: Блок puml остаётся кодом
- **WHEN** страница содержит блок ```` ```puml ```` с примером диаграммы
- **THEN** в выходах он остаётся блоком кода с исходным текстом

#### Scenario: Ошибка в блоке
- **WHEN** блок ```` ```plantuml ```` не компилируется
- **THEN** сборка завершается с кодом 0, на месте блока заглушка, предупреждение называет исходный `.md`-файл

#### Scenario: Пользовательский шаблон с клиентским рендером
- **WHEN** проект с пользовательским `docsifyTemplate`, подключающим `docsify-plantuml`, содержит блок ```` ```plantuml ```` в странице
- **THEN** выходная страница не содержит блока `plantuml`, и браузер не обращается к сервису рендера

### Requirement: Автоматическая проверка офлайн-сайта
Тесты SHALL собирать шаблонный проект и проверять отсутствие адресов внешних доменов в `index.html`, CSS и страницах выхода по правилу требования «Сайт по умолчанию не обращается к внешним доменам». Найденный адрес MUST называться в сообщении теста вместе с файлом.

#### Scenario: Регресс ловится тестом
- **WHEN** во встроенный шаблон добавлен `<script src="https://cdn.example/x.js">`
- **THEN** тест падает с сообщением, называющим `index.html` и адрес

## openapi-plugin

[Обзор](#C4-Builder)

# openapi-plugin Specification

## Purpose
Публикация набора OpenAPI-контрактов на docsify-сайте: страница swagger-ui на каждую спеку из
локальной папки или архива репозитория контрактов, полностью офлайн — без внешних CDN и без
запросов из браузера читателя за пределы сайта.

## Requirements

### Requirement: Раздел API из набора спек

Встроенный плагин `openapi` SHALL строить раздел сайта под точкой монтирования (`mount`, по
умолчанию `API`) из файлов источника (`dir` либо `archive` — ровно один), отобранных по
`glob` (по умолчанию `**/openapi.{yaml,yml,json}`). На каждую найденную спеку MUST быть
страница с именем родительской папки спеки (для файла в корне источника — имя файла без
расширения); страница-сводка раздела MUST перечислять спеки со ссылками по алфавиту. Пустое
совпадение `glob` MUST прерывать сборку с указанием источника и шаблона.

#### Scenario: Спеки репозитория контрактов
- **WHEN** источник — архив репозитория с `finch/openapi.yaml`, `selling-agent/openapi.yaml`, `common/openapi.yaml`
- **THEN** раздел содержит страницы `finch`, `selling-agent`, `common` и сводку со ссылками на них

#### Scenario: Ни одна спека не найдена
- **WHEN** `glob` не совпадает ни с одним файлом источника
- **THEN** сборка прерывается с сообщением, содержащим источник и шаблон

#### Scenario: Ошибка конфигурации источника
- **WHEN** заданы одновременно `dir` и `archive` либо ни один из них
- **THEN** сборка не стартует, ошибка называет плагин и опции

### Requirement: Страница спеки — офлайн swagger-ui

Страница спеки SHALL отображать её через swagger-ui, подключённый из ассетов сайта (скрипт и
стиль вендорены в пакет и копируются в выходной каталог). Файл спеки MUST копироваться в
выходной каталог, сохраняя относительный путь внутри источника, и загружаться swagger-ui
относительной ссылкой — так относительные `$ref` между спеками продолжают разрешаться. Страница
MUST NOT ссылаться на внешние CDN, MUST NOT обращаться к внешнему валидатору спек (бейдж
валидации swagger-ui выключен) и MUST NOT требовать доступа к исходному репозиторию у
читателя. Плагин SHALL требовать выполнения скриптов на страницах (`executeScript`).

#### Scenario: Открытие страницы без сети
- **WHEN** собранный сайт открыт в браузере без доступа к интернету и к GitLab
- **THEN** страница спеки отрисовывает swagger-ui с содержимым спеки

#### Scenario: Относительные $ref
- **WHEN** `finch/openapi.yaml` ссылается на `../common/openapi.yaml#/components/schemas/Error`
- **THEN** swagger-ui разрешает ссылку по скопированному рядом файлу `common/openapi.yaml`

#### Scenario: executeScript выключен в конфиге
- **WHEN** в `.c4builder` `executeScript: false`, а плагин `openapi` подключён
- **THEN** сайт собирается с выполнением скриптов, о чём сообщается в логе

#### Scenario: Нет запроса к валидатору
- **WHEN** страница спеки открыта в браузере
- **THEN** swagger-ui не показывает бейдж валидации и не обращается к `validator.swagger.io`

### Requirement: Источник — локальная папка или архив без авторизации по умолчанию

Плагин SHALL получать спеки через резолвер источников ядра. Для публичного или
внутренне-видимого репозитория `archive` MUST работать без заголовков авторизации; `headers` — опция.
При `dir` папка SHALL объявляться путём наблюдения для watch-режима; при `archive`
повторные сборки в одном процессе MUST переиспользовать скачанный архив.

#### Scenario: Архив без токена
- **WHEN** задан `archive` на архив репозитория с внутренней видимостью и `headers` не заданы
- **THEN** архив скачивается без заголовка авторизации, страницы строятся

#### Scenario: Локальная папка в watch-режиме
- **WHEN** источник — `dir` и в нём меняется спека при `-w`
- **THEN** сайт пересобирается с обновлённой спекой

## openspec-plugin

[Обзор](#C4-Builder)

# openspec-plugin Specification

## Purpose
Публикация локального OpenSpec-store на docsify-сайте: сводка, активные change'ы, актуальные
спеки и архив как обычные страницы сборки — с поиском, sidebar и локальным рендером диаграмм
артефактов.

## Requirements

### Requirement: Раздел OpenSpec из локального store

Встроенный плагин `openspec` SHALL строить раздел сайта из папки store (`dir`, по умолчанию
`openspec` относительно текущего каталога) под точкой монтирования (`mount`, по умолчанию
`OpenSpec`) — дочерним разделом корня сайта. Раздел MUST содержать: страницу-сводку,
подраздел активных change'ов, подраздел спек, подраздел архива. Отсутствие папки store MUST
прерывать сборку с указанием пути. Пустой store (без change'ов и спек) SHALL давать раздел с
нулевыми счётчиками, а не ошибку.

#### Scenario: Раздел в sidebar
- **WHEN** в `.c4builder` подключён плагин `openspec` и store содержит change'ы и спеки
- **THEN** sidebar сайта содержит раздел с именем `mount` и вложенные подразделы change'ов, спек и архива

#### Scenario: Переименование раздела
- **WHEN** задано `mount: "Планы"`
- **THEN** раздел и его путь в выходном каталоге используют это имя

#### Scenario: Store не найден
- **WHEN** папка `dir` отсутствует
- **THEN** сборка прерывается с сообщением, содержащим ожидаемый путь

### Requirement: Сводка store

Страница-сводка SHALL показывать число активных change'ов, число спек, число архивных
change'ов и суммарный прогресс задач (выполнено/всего) по активным change'ам, а также
таблицу активных change'ов со ссылкой на страницу каждого, прогрессом его задач и датой
последнего изменения артефактов, отсортированную по дате изменения от новых к старым.

#### Scenario: Прогресс в сводке
- **WHEN** у активного change'а в `tasks.md` 23 пункта-чекбокса, из них 12 отмечены
- **THEN** строка таблицы показывает `12/23`, а суммарный прогресс учитывает эти числа

#### Scenario: Change без tasks
- **WHEN** у change'а нет `tasks.md` или в нём нет чекбоксов
- **THEN** прогресс отображается как отсутствующий (не `0/0` с ошибкой деления), сводка строится

### Requirement: Страница change'а и подстраницы артефактов

Каждая папка внутри `changes/` (кроме `archive/`) SHALL давать страницу с именем папки
(идентификатор change'а) и вложенные подстраницы. Порядок артефактов задаёт опция плагина
`artifacts` (по умолчанию `proposal, design, tasks`): первый артефакт списка, если он есть в
change'е, MUST выводиться прямо на странице change'а; остальные `*.md` корня папки — отдельными
подстраницами с именем артефакта в порядке списка, затем не перечисленные — по алфавиту.
Дельты спек из `specs/**/spec.md` change'а SHALL публиковаться подразделом `specs` со
страницей на дельту, повторяя структуру папок. Шапка страницы change'а MUST содержать
метаданные (схема, дата создания — если есть), прогресс задач и ссылки на все подстраницы.
Пункты `- [ ]`/`- [x]` MUST сохраняться как чекбоксы.

#### Scenario: Полный change
- **WHEN** change содержит `proposal.md`, `design.md`, `tasks.md`, `specs/<путь>/spec.md`
- **THEN** страница change'а показывает шапку с прогрессом, ссылки на подстраницы и текст proposal; в sidebar под change'ем идут `design`, `tasks`, `specs → <путь>`

#### Scenario: Нестандартные артефакты и порядок
- **WHEN** change создан по кастомной схеме и содержит `plan.md`, `notes.md`, а `artifacts: ["plan"]`
- **THEN** `plan` выводится на странице change'а, `notes` — подстраницей; сборка не требует знания схемы

#### Scenario: Ссылки между артефактами
- **WHEN** артефакт ссылается относительной ссылкой на другой артефакт того же change'а (`design.md`, `tasks.md#done`, `specs/<путь>/spec.md`) либо на файл (картинку) в папке change'а
- **THEN** ссылка ведёт на соответствующую страницу сайта (с сохранением якоря), а файл копируется к странице, где на него ссылаются

### Requirement: Диаграммы артефактов рендерятся локально

Блоки кода ```plantuml и ```d2 в артефактах SHALL извлекаться в диаграммы страницы и
рендериться локальным движком сборки в выбранном `diagramFormat`; в тексте на их месте
MUST стоять изображение. Онлайн-сервисы рендера MUST NOT использоваться; клиентский
рендер в браузере для этих блоков MUST NOT срабатывать.

#### Scenario: PlantUML в design.md
- **WHEN** `design.md` содержит блок ```plantuml с C4-диаграммой на stdlib
- **THEN** страница содержит отрендеренное изображение на его месте, а исходный текст блока не отправляется никуда за пределы процесса сборки

#### Scenario: Ошибка синтаксиса диаграммы
- **WHEN** блок диаграммы не компилируется
- **THEN** сборка сообщает об ошибке с идентификатором change'а и именем артефакта по общим правилам рендера

### Requirement: Подраздел спек

Спеки из `specs/` SHALL публиковаться страницами, повторяя структуру папок store (одно- и
двухуровневая раскладка: `specs/<capability>/spec.md` и `specs/<область>/<capability>/spec.md`).
Промежуточные папки SHALL становиться подразделами со списком вложенных спек. Имя страницы —
имя папки capability.

#### Scenario: Двухуровневые спеки
- **WHEN** store содержит `specs/payments/refunds/spec.md`
- **THEN** в sidebar есть `Specs → payments → refunds`, страница показывает содержимое `spec.md`

### Requirement: Подраздел архива

Папки `changes/archive/*` SHALL публиковаться так же, как активные change'ы, в подразделе
архива, отсортированные по имени папки от новых к старым (префикс даты в имени). Сводка
подраздела архива MUST перечислять архивные change'ы со ссылками.

#### Scenario: Архивный change
- **WHEN** в `changes/archive/2026-08-13-dig-33841-ai-answer-disclaimer/` есть артефакты
- **THEN** страница доступна в подразделе архива и не учитывается в счётчике активных change'ов

### Requirement: Watch-режим отслеживает store

Плагин SHALL объявлять папку store как путь наблюдения.

#### Scenario: Правка артефакта при -w
- **WHEN** в watch-режиме меняется `tasks.md` активного change'а
- **THEN** сайт пересобирается, прогресс на странице и в сводке обновляется

## output-formats

[Обзор](#C4-Builder)

# output-formats Specification

## Purpose
Набор выходов сборки: коллекция markdown, единый complete-markdown, docsify-сайт и `llms.txt`/`llms-full.txt` для агентов; удалённый PDF-вывод и поведение на легаси-конфигах.

## Requirements

### Requirement: Поддерживаемые типы вывода
Сборка SHALL поддерживать три типа вывода: множественные markdown-файлы
(`generateMD`), единый complete-markdown (`generateCompleteMD`) и website
(`generateWEB`), а также дополнение website для агентов — `llms.txt` и
`llms-full.txt` (`generateLLMS`). PDF-вывод (множественные PDF-файлы и единый
complete-PDF) MUST NOT поддерживаться, а зависимость `md-to-pdf` и связанный
headless-браузер MUST отсутствовать в зависимостях пакета.

#### Scenario: Сборка доступных выходов
- **WHEN** в `.c4builder` включены `generateMD`, `generateCompleteMD`, `generateWEB` и/или `generateLLMS`
- **THEN** сборка формирует соответствующие выходы и не порождает PDF-файлов

#### Scenario: PDF-зависимость отсутствует
- **WHEN** просматриваются зависимости пакета
- **THEN** `md-to-pdf` (и транзитивный headless-браузер) в них отсутствует, файла `pdf.css` в пакете нет

### Requirement: Мастер настройки не предлагает PDF
Интерактивный мастер настройки (`c4builder config`) MUST NOT предлагать PDF-форматы
в выборе типов вывода и MUST NOT спрашивать про пользовательский PDF-CSS. Наличие
или отсутствие PDF-ключей в конфиге MUST NOT влиять на то, показывается ли вопрос
о выборе форматов.

#### Scenario: Выбор форматов в мастере
- **WHEN** пользователь запускает мастер настройки
- **THEN** в списке форматов присутствуют только markdown, complete-markdown, website и `llms.txt`, а вопрос про PDF-CSS не задаётся

#### Scenario: Конфиг без PDF-ключей не ре-триггерит вопрос
- **WHEN** запускается сборка с конфигом, где выбраны форматы, но PDF-ключи отсутствуют
- **THEN** мастер выбора форматов не показывается повторно из-за отсутствия PDF-ключей

### Requirement: Легаси-конфиг с PDF не ломает сборку
Сборка SHALL продолжаться и завершаться успешно (код возврата 0), собрав все прочие
включённые выходы, при наличии в существующем `.c4builder` истинного (truthy)
значения `generatePDF` и/или `generateCompletePDF`. Сборка MUST напечатать
предупреждение, что PDF-вывод удалён, перечислив в нём **только реально
присутствующие truthy PDF-ключи**, и подсказать удалить их из `.c4builder` вручную.
Сборка MUST NOT изменять файл конфигурации.

#### Scenario: Truthy PDF-ключ в конфиге
- **WHEN** в `.c4builder` `generatePDF: true` и включены другие выходы
- **THEN** печатается предупреждение с ключом `generatePDF` и подсказкой удалить его, markdown/website собираются, процесс завершается с кодом 0, а `.c4builder` остаётся без изменений

#### Scenario: В предупреждении только присутствующие ключи
- **WHEN** truthy только `generateCompletePDF`, а `generatePDF` равен `false` или отсутствует
- **THEN** предупреждение перечисляет `generateCompletePDF` и не упоминает `generatePDF`

#### Scenario: PDF выключен или не задан
- **WHEN** `generatePDF` и `generateCompletePDF` равны `false` или отсутствуют в конфиге
- **THEN** предупреждение о PDF не печатается

### Requirement: Оглавление llms.txt
При включённых `generateLLMS` и `generateWEB` сборка SHALL записывать в корень
выходного каталога файл `llms.txt` в формате llmstxt.org: заголовок H1 с именем
проекта, blockquote с кратким описанием и ссылкой на `llms-full.txt`, секция H2
со списком страниц `- [заголовок](ссылка)`. Список MUST повторять набор и порядок
страниц sidebar сайта (страницы, исключённые `excludeSidebarFolderByPath`, в него
не входят; виртуальные страницы плагинов — входят). Заголовок страницы MUST быть
её путём от корня через ` / ` (корень — имя главной страницы). Ссылка MUST быть
относительным URL-кодированным путём к markdown-файлу страницы, который реально
лежит в выходном каталоге сайта. Список MUST быть плоским (без вложенных списков).

#### Scenario: Оглавление совпадает с sidebar
- **WHEN** собирается демо-проект шаблона с `generateWEB: true` и `generateLLMS: true`
- **THEN** `llms.txt` перечисляет те же страницы и в том же порядке, что `_sidebar.md`, и каждая ссылка указывает на существующий в выходном каталоге `.md`-файл

#### Scenario: Заголовок — путь страницы
- **WHEN** в проекте есть страница `1 Internet Banking System/API Application`
- **THEN** её строка в `llms.txt` имеет заголовок `1 Internet Banking System / API Application`, а ссылка — URL-кодированный путь к её `.md`

#### Scenario: Исключённая из sidebar папка
- **WHEN** папка указана в `excludeSidebarFolderByPath`
- **THEN** её страницы отсутствуют и в `_sidebar.md`, и в `llms.txt`

#### Scenario: Страницы плагина
- **WHEN** включён плагин, добавляющий виртуальные страницы (например, `openspec`)
- **THEN** эти страницы присутствуют в `llms.txt` на своих местах в порядке sidebar

### Requirement: Полный текст llms-full.txt с исходниками диаграмм
При включённых `generateLLMS` и `generateWEB` сборка SHALL записывать в корень
выходного каталога `llms-full.txt`: текст всех страниц проекта в том же составе и
порядке, что complete-markdown. Каждая диаграмма MUST быть вставлена исходным текстом
в fenced-блок с языком движка (`plantuml` для `.puml`, включая ditaa, и `d2` для `.d2`)
на том же месте, где на странице стоит изображение, а не ссылкой на изображение и не
base64. Представление диаграмм в `llms-full.txt` MUST NOT зависеть от
`diagramFormat`, `embedDiagram`, `includeLinkToDiagram` и `generateLocalImages`.
Fenced-блок MUST оставаться корректным, даже если исходник содержит обратные кавычки.

#### Scenario: PlantUML-диаграмма исходником
- **WHEN** страница содержит `context.puml`
- **THEN** в `llms-full.txt` на месте диаграммы стоит блок ```` ```plantuml ```` с текстом `context.puml` без изменений, а ссылки на `context.svg` нет

#### Scenario: D2-диаграмма исходником
- **WHEN** страница содержит `.d2`-диаграмму
- **THEN** в `llms-full.txt` она представлена блоком ```` ```d2 ```` с её исходным текстом

#### Scenario: Диаграмма из fenced-блока артефакта плагина
- **WHEN** артефакт OpenSpec содержит fenced-блок `plantuml`, превращённый плагином в диаграмму страницы
- **THEN** в `llms-full.txt` на его месте стоит fenced-блок `plantuml` с тем же исходником

#### Scenario: Независимость от настроек изображений
- **WHEN** проект собирается с `embedDiagram: true` и `diagramFormat: png`
- **THEN** `llms-full.txt` не содержит `data:image` и ссылок на PNG диаграмм — только исходники

### Requirement: Локальные include-файлы диаграмм в приложении
`llms-full.txt` SHALL завершаться приложением, где каждый локальный файл, подключённый
диаграммами проекта (PlantUML `!include` и его варианты, D2-импорты `@`/`...@`),
включая вложенные, приведён ровно один раз: путь относительно каталога проекта
(posix-разделители) и fenced-блок с содержимым. Файлы MUST быть упорядочены по пути.
Стандартная библиотека (`!include <…>`) и URL-инклюды MUST NOT разворачиваться и
MUST оставаться строками в исходнике диаграммы. Директивы `!include` в исходниках
диаграмм MUST NOT изменяться. Без локальных инклюдов приложение MUST отсутствовать.

#### Scenario: Общий файл стилей приведён один раз
- **WHEN** две диаграммы подключают один и тот же `styles.iuml`
- **THEN** приложение содержит `styles.iuml` ровно один раз, а исходники обеих диаграмм сохраняют строку `!include`

#### Scenario: Вложенный инклюд
- **WHEN** `a.iuml`, подключённый диаграммой, сам подключает `b.iuml`
- **THEN** приложение содержит оба файла

#### Scenario: stdlib не разворачивается
- **WHEN** диаграмма подключает `!include <C4/C4_Container>`
- **THEN** в приложении нет записи для C4-PlantUML, а строка остаётся в исходнике диаграммы

#### Scenario: D2-импорт
- **WHEN** `.d2`-диаграмма импортирует `_c4lib.d2`
- **THEN** приложение содержит `_c4lib.d2` с его содержимым в блоке `d2`

### Requirement: llms-вывод требует website
При `generateLLMS: true` и выключенном `generateWEB` сборка SHALL завершаться успешно
(код возврата 0), собрав прочие включённые выходы, MUST NOT создавать `llms.txt` и
`llms-full.txt` и MUST печатать предупреждение, что `generateLLMS` требует `generateWEB`.

#### Scenario: Website выключен
- **WHEN** в `.c4builder` `generateLLMS: true`, `generateWEB: false`, `generateMD: true`
- **THEN** markdown собирается, `llms.txt`/`llms-full.txt` отсутствуют, напечатано предупреждение о `generateWEB`, код возврата 0

### Requirement: Конфиг без generateLLMS не меняет вывод
Отсутствие ключа `generateLLMS` в существующем `.c4builder` SHALL означать, что
llms-вывод выключен: выход сборки MUST совпадать с выходом до появления ключа. Отсутствие
ключа MUST NOT приводить к повторному показу вопроса о форматах в мастере настройки.

#### Scenario: Легаси-конфиг собирается как раньше
- **WHEN** собирается проект, в `.c4builder` которого нет `generateLLMS`
- **THEN** `llms.txt` и `llms-full.txt` не создаются, остальные файлы выхода побайтно совпадают с golden-эталоном

#### Scenario: Отсутствие ключа не ре-триггерит мастер
- **WHEN** запускается сборка с конфигом, где форматы выбраны, а `generateLLMS` отсутствует
- **THEN** мастер выбора форматов не показывается повторно из-за отсутствия `generateLLMS`

## plugin-system

[Обзор](#C4-Builder)

# plugin-system Specification

## Purpose
Расширение сборки внешними источниками без правки ядра: плагины, объявленные в `.c4builder`,
добавляют в дерево сборки виртуальные страницы и диаграммы, ассеты сайта и пути наблюдения,
а ядро валидирует их опции и загружает их до старта сборки.

## Requirements

### Requirement: Плагины объявляются в конфигурации

`.c4builder` SHALL принимать ключ `plugins` — список записей, каждая из которых либо строка
(идентификатор плагина с опциями по умолчанию), либо пара `[идентификатор, объект опций]`.
Идентификатор MUST резолвиться в одном из порядков: встроенный плагин по имени, локальный
модуль по пути относительно текущего каталога, npm-пакет по имени. Значение ключа неверной
формы MUST отклоняться понятной ошибкой с путём ключа при загрузке опций. Отсутствие ключа
SHALL означать пустой список — поведение сборки без плагинов не меняется.

#### Scenario: Строка и пара равнозначны
- **WHEN** в `plugins` указано `"openspec"` либо `["openspec", {}]`
- **THEN** загружается встроенный плагин `openspec` с опциями по умолчанию

#### Scenario: Локальный модуль и npm-пакет
- **WHEN** идентификатор начинается с `./`, `../` или `/`, либо не совпадает со встроенным именем
- **THEN** модуль загружается соответственно по пути от текущего каталога либо как npm-пакет; несуществующий модуль даёт ошибку с идентификатором и причиной

#### Scenario: Неверная форма ключа
- **WHEN** `plugins` — не массив либо содержит запись не строкового и не парного вида
- **THEN** загрузка опций завершается ошибкой, называющей `plugins` и позицию записи

#### Scenario: Совместимость с прежними версиями
- **WHEN** конфиг с ключом `plugins` читает версия без поддержки плагинов
- **THEN** ключ игнорируется, сборка проходит без разделов плагинов

### Requirement: Опции плагина валидируются его схемой до старта сборки

Плагин MAY объявить схему своих опций. Ядро SHALL валидировать опции по ней при загрузке
плагина, до начала сборки; ошибка MUST называть плагин, ключ опции и причину. Дефолты схемы
MUST применяться к отсутствующим опциям. Схема встроенных плагинов MUST быть строгой:
неизвестный ключ опции — ошибка. До валидации в строковых опциях SHALL подставляться
переменные окружения вида `${NAME}`; незаданная переменная даёт пустую строку.

#### Scenario: Ошибка типа опции
- **WHEN** опция плагина имеет неверный тип
- **THEN** сборка не стартует, ошибка содержит имя плагина, ключ и ожидаемый тип

#### Scenario: Неизвестная опция встроенного плагина
- **WHEN** в опциях встроенного плагина есть ключ, не описанный схемой (например, опечатка)
- **THEN** сборка не стартует, ошибка называет неизвестный ключ

#### Scenario: Плагин без схемы
- **WHEN** сторонний плагин не объявляет схему опций
- **THEN** опции передаются ему без изменений

#### Scenario: Подстановка окружения
- **WHEN** опция содержит `${GITLAB_TOKEN}` и переменная задана
- **THEN** плагин получает опцию с подставленным значением, а значение не попадает в вывод сборки и логи

### Requirement: Виртуальные страницы через хук после скана

Ядро SHALL вызывать хук плагина `afterScan` после построения дерева исходников и до рендера,
передавая дерево и опции сборки. Плагин MAY добавить в дерево виртуальные элементы —
страницы с markdown-содержимым и диаграммами, не имеющие файлов в каталоге исходников.
Виртуальные элементы MUST проходить штатные фазы наравне с реальными: рендер их диаграмм
локальным движком, генерация страниц сайта и markdown, sidebar, поиск сайта, complete-документ.
Порядок вызова хуков SHALL совпадать с порядком записей `plugins`; ошибка хука MUST прерывать
сборку с именем плагина.

#### Scenario: Виртуальный раздел на сайте
- **WHEN** плагин добавил виртуальные элементы под точкой монтирования
- **THEN** в собранном сайте есть их страницы и записи sidebar на соответствующем уровне вложенности, а поиск сайта находит их текст

#### Scenario: Диаграммы виртуальных страниц рендерятся локально
- **WHEN** виртуальный элемент содержит диаграмму PlantUML
- **THEN** она рендерится тем же локальным движком, что диаграммы из исходников, и попадает в страницу как изображение; онлайн-сервисы не используются

#### Scenario: Виртуальные страницы в остальных выходах
- **WHEN** включены `generateMD` и/или `generateCompleteMD`
- **THEN** виртуальные страницы присутствуют в этих выходах наравне с реальными

#### Scenario: Ошибка плагина
- **WHEN** хук плагина бросает исключение
- **THEN** сборка прерывается с сообщением, содержащим имя плагина и текст ошибки; бэкап предыдущей сборки сохраняется по общим правилам

### Requirement: Ассеты плагинов и хук после сборки

Ядро SHALL вызывать хук `afterBuild` после генерации выходов, передавая путь выходного
каталога и опции. Плагин MAY объявить скрипты и стили для сайта: ядро MUST скопировать их в
выходной каталог и подключить в `index.html` пост-обработкой готового HTML — независимо от
того, используется ли пользовательский `docsifyTemplate`. Плагин MAY потребовать включения
`executeScript`; тогда сборка ведёт себя как при `executeScript: true`.

#### Scenario: Ассеты при пользовательском шаблоне
- **WHEN** сайт собирается с `docsifyTemplate` из репозитория и плагин объявил стиль и скрипт
- **THEN** `index.html` содержит подключения этих ассетов, а сами файлы лежат в выходном каталоге; шаблон править не требуется

#### Scenario: Плагину нужен executeScript
- **WHEN** в конфиге `executeScript: false`, но подключён плагин, требующий выполнения скриптов на страницах
- **THEN** сайт собирается с выполнением скриптов, в лог выводится сообщение о причине

### Requirement: Плагины участвуют в режиме наблюдения

Плагин MAY объявить дополнительные пути наблюдения. В watch-режиме изменения по этим путям
MUST вызывать пересборку так же, как изменения в каталоге исходников.

#### Scenario: Изменение вне каталога исходников
- **WHEN** запущен `--site -w` и меняется файл под объявленным плагином путём (например, `openspec/`)
- **THEN** сайт пересобирается и отражает изменение

### Requirement: Источники плагинов — локальная папка или архив

Ядро SHALL предоставлять плагинам резолвер источника: `dir` — путь к локальной папке;
`archive` — HTTP(S)-URL архива tar.gz или zip с опциональными `subdir` и `headers` (карта HTTP-заголовков; пустые значения после подстановки окружения отбрасываются). Результат
резолва — локальный каталог; для `archive` ядро MUST скачать и распаковать архив в кэш-каталог
внутри процесса сборки. В watch-режиме архив SHALL скачиваться один раз на процесс.
Недоступный источник MUST прерывать сборку с URL/путём и причиной. Распаковка MUST отвергать
записи с путями вне целевого каталога.

#### Scenario: Локальная папка
- **WHEN** источник задан как `dir`
- **THEN** плагин получает путь к этой папке; отсутствие папки — ошибка с указанием пути

#### Scenario: Архив по HTTP
- **WHEN** источник задан как `archive` с URL tar.gz
- **THEN** архив скачивается (с заданными непустыми `headers`), распаковывается, и плагин получает путь к каталогу `subdir` внутри распакованного архива

#### Scenario: Архив в watch-режиме
- **WHEN** сборка в режиме `-w` перезапускается после правки исходников
- **THEN** ранее скачанный архив не скачивается повторно

#### Scenario: Недоступный архив
- **WHEN** запрос архива завершается ошибкой HTTP или сети
- **THEN** сборка прерывается с URL и кодом/причиной, без частичного раздела на сайте

## project-scaffold

[Обзор](#C4-Builder)

# project-scaffold Specification

## Purpose
Создание нового проекта командой `c4builder --new` / `c4builder new`: флаги, неинтерактивный режим и единый источник значений по умолчанию для headless-сборки.

## Requirements

### Requirement: Флаги команды создания проекта
Команда `c4builder --new` SHALL принимать имя проекта через флаг `--name <name>`;
переданное значение MUST подставляться вместо интерактивного вопроса об имени.
Создание проекта MUST NOT предлагать VSCode-сниппеты — ни промптом, ни флагом — и
MUST NOT создавать каталог `.vscode` в проекте.

#### Scenario: Флаг имени заменяет промпт
- **WHEN** `c4builder --new --name demo` без `--yes`
- **THEN** вопрос об имени не задаётся, а VSCode-сниппеты не предлагаются

#### Scenario: Интерактивное создание спрашивает только имя
- **WHEN** `c4builder --new` без `--name` и без `--yes`
- **THEN** задаётся единственный вопрос — имя проекта; вопрос о VSCode-сниппетах не задаётся

#### Scenario: VSCode-каталог не создаётся
- **WHEN** проект создан через `c4builder --new` любым способом
- **THEN** каталог `.vscode` и файл сниппетов в проекте отсутствуют

### Requirement: Явный неинтерактивный режим
С флагом `-y` / `--yes` создание проекта SHALL проходить без единого интерактивного
вопроса. В этом режиме `--name` MUST быть задан; отсутствие `--name` или невалидное
значение (имя со слэшем, непустая целевая папка) MUST приводить к
понятной ошибке и ненулевому коду возврата, а НЕ к повторному запросу. Неуказанные
флагами значения MUST браться из дефолтов.

#### Scenario: Полностью неинтерактивное создание
- **WHEN** `c4builder --new --yes --name demo` в пустой директории
- **THEN** проект создаётся без промптов, процесс завершается с кодом 0

#### Scenario: --yes без имени
- **WHEN** `c4builder --new --yes` без `--name`
- **THEN** создание завершается понятной ошибкой и ненулевым кодом возврата, без промптов

#### Scenario: --yes с занятой папкой
- **WHEN** `c4builder --new --yes --name demo`, а папка `demo` существует и не пуста
- **THEN** создание завершается понятной ошибкой и ненулевым кодом возврата, без промптов

### Requirement: Полный конфиг для headless-сборки
В режиме `--yes` создание проекта SHALL записывать в `.c4builder` полный набор
настроек (типы выходов и их под-опции, формат диаграмм, кодировку, локальный рендер),
достаточный, чтобы последующий запуск `c4builder` собрал проект без интерактивного
wizard'а. Значения по умолчанию для выходов MUST включать website, множественные
markdown и llms-вывод (`generateLLMS: true`), `diagramFormat=svg`, локальный рендер
диаграмм и `UTF-8`.

#### Scenario: Сборка после --yes не спрашивает
- **WHEN** проект создан через `c4builder --new --yes --name demo`, затем в нём
  запущен `c4builder`
- **THEN** сборка проходит без интерактивных вопросов и формирует выходы по
  записанным дефолтам, включая `llms.txt` и `llms-full.txt`

#### Scenario: Интерактивное создание не пишет полный конфиг
- **WHEN** проект создан интерактивно (без `--yes`)
- **THEN** поведение записи `.c4builder` остаётся прежним, а первая сборка ведёт
  пользователя через wizard как раньше

### Requirement: Единый источник значений по умолчанию
Значения по умолчанию для настроек проекта SHALL задаваться в едином месте
(`defaultConfig`), которое используется и при записи полного конфига в режиме `--yes`,
и как источник дефолтов интерактивного wizard'а. Дефолты в неинтерактивном создании и
в wizard'е MUST совпадать.

#### Scenario: Совпадение дефолтов
- **WHEN** сравниваются значения по умолчанию, предлагаемые wizard'ом, и значения,
  записанные `new --yes` без явных флагов
- **THEN** они совпадают (единый источник, без дублирования)

## project-template

[Обзор](#C4-Builder)

# project-template

## Purpose

Требования к демо-проекту, создаваемому командой `c4builder new`: офлайн-сборка, stdlib-инклюды C4-PlantUML, демонстрация локальных `.iuml` и кириллицы.

## Requirements

### Requirement: Демо-проект собирается офлайн
Проект, созданный `c4builder new`, SHALL собираться без доступа в интернет: рендер всех диаграмм шаблона (PlantUML, D2, BPMN) MUST выполняться локальными движками без сетевых обращений.

#### Scenario: Сборка нового проекта без сети
- **WHEN** проект создан из шаблона и `c4builder` запущен в окружении без доступа в интернет
- **THEN** сборка завершается успешно и все диаграммы шаблона отрендерены

### Requirement: Диаграммы шаблона используют stdlib-инклюды
Все `.puml` шаблона MUST подключать C4-PlantUML через stdlib (`!include <C4/...>`); http(s)-инклюды в шаблоне и в VS Code-сниппетах (`C4.code-snippets`) MUST отсутствовать.

#### Scenario: Проверка инклюдов шаблона
- **WHEN** просматриваются `.puml` шаблона и файл сниппетов
- **THEN** ни один не содержит `!include http`, а C4-диаграммы используют `!include <C4/...>`

### Requirement: Шаблон демонстрирует локальный .iuml
Шаблон MUST содержать общий `.iuml`-файл (стили/тема), подключаемый минимум из двух диаграмм относительным `!include`.

#### Scenario: Сборка диаграмм с .iuml-инклюдом
- **WHEN** собирается новый проект из шаблона
- **THEN** диаграммы, подключающие общий `.iuml`, рендерятся успешно с применёнными стилями

### Requirement: Шаблон демонстрирует кириллицу
Шаблон MUST содержать страницу с русским md-текстом и диаграмму с кириллическими подписями элементов.

#### Scenario: Кириллица в собранном выходе
- **WHEN** собирается новый проект из шаблона
- **THEN** кириллический текст присутствует без искажений в выходных md и в SVG кириллической диаграммы

### Requirement: Шаблон содержит инструкции для агента
Проект, созданный `c4builder --new`, SHALL содержать в корне файл `AGENTS.md` на английском языке, который описывает: сборку (`c4builder`), проверку отдельных диаграмм (`c4builder check <file...>`), живой просмотр (`c4builder --site -w`), расположение исходников (`src/`) и конвенции диаграмм (stdlib-инклюды `<C4/...>`, общий `.iuml`, офлайн-рендер), а также команду установки скиллов `npx skills add AlfaCapital-Tech/C4-Builder/skills`. `AGENTS.md` MUST NOT попадать в выходы сборки (сайт, markdown, complete-markdown).

#### Scenario: AGENTS.md в новом проекте
- **WHEN** проект создан командой `c4builder --new --name demo -y`
- **THEN** в каталоге `demo/` есть `AGENTS.md` с командами `c4builder`, `c4builder check` и `npx skills add AlfaCapital-Tech/C4-Builder/skills`

#### Scenario: AGENTS.md не попадает в выходы
- **WHEN** новый проект собран командой `c4builder`
- **THEN** в каталоге выходов нет файла `AGENTS.md`, а сгенерированные страницы не содержат его текста

### Requirement: Шаблон демонстрирует BPMN-процесс
Шаблон MUST содержать раздел с `.bpmn`-диаграммой без координат (без BPMN DI), с несколькими пулами, дорожками, событием-таймером и message flow, с кириллическими подписями, и md-страницей, поясняющей, что агент пишет только семантическую часть, а раскладку делает сборка.

#### Scenario: BPMN-пример в новом проекте
- **WHEN** собирается новый проект из шаблона
- **THEN** BPMN-диаграмма раздела отрендерена с горизонтальными пулами и дорожками, а `c4builder check` для её файла завершается с кодом 0

## regression-testing

[Обзор](#C4-Builder)

# regression-testing

## Purpose

Требования к golden-тесту сборки: fixture'ом служит демо-шаблон `template/src`, полное дерево выходных файлов сверяется с закоммиченным эталоном после нормализации, повторная сборка с кэшем идентична, эталон обновляется только явной командой.

## Requirements

### Requirement: Golden-сборка fixture соответствует эталону
Тестовый набор SHALL собирать fixture-проект «мини-arch» реальным запуском CLI (неинтерактивно, с готовым `.c4builder`) во временной директории для каждого варианта матрицы конфигураций и сравнивать полное дерево выходных файлов (site, md, complete-md, диаграммы) с закоммиченным эталоном этого варианта (`test/golden/<variant>/`). Сравнение MUST выполняться после нормализации (удаление XML-комментариев из SVG, приведение переводов строк к LF) и MUST включать идентичность списка файлов. Варианты MUST собираться из одних и тех же исходников `template/src`; различаются только fixture-конфиги (`test/fixtures/<variant>.c4builder.json`).

#### Scenario: Совпадение с эталоном
- **WHEN** golden-тест запускает сборку fixture варианта и выход совпадает с эталоном этого варианта после нормализации
- **THEN** тест варианта проходит

#### Scenario: Расхождение с эталоном
- **WHEN** содержимое хотя бы одного выходного файла или сам список файлов отличается от эталона варианта
- **THEN** тест падает с диффом, указывающим вариант, конкретные файлы и расхождения

#### Scenario: Изоляция вариантов
- **WHEN** собираются несколько вариантов матрицы
- **THEN** каждый вариант работает в отдельной временной директории со своим `.c4builder` и `.c4builder.cache`, не влияя на выход других вариантов

### Requirement: Fixture — демо-шаблон проекта
Fixture'ом golden-теста SHALL служить существующий демо-шаблон `template/src` (stdlib-инклюды, локальный `.iuml`, `.d2` с импортом, кириллица). Тест-хелпер MUST копировать шаблон во временную директорию и класть готовый `.c4builder` выбранного варианта из `test/fixtures/<variant>.c4builder.json`. Вариант `default` MUST сохранять текущий контракт: `diagramFormat=svg`, `generateLocalImages=true`, выходы site/md/complete-md, navigation/TOC/breadcrumbs.

#### Scenario: Сборка fixture из шаблона
- **WHEN** golden-тест собирает копию шаблона с конфигом варианта `default`
- **THEN** в выходе присутствуют SVG для stdlib-диаграмм и для диаграмм с `.iuml`-инклюдом, а кириллица сохранена в выходных md и SVG

### Requirement: Повторная сборка с кэшем идентична первой
Повторный запуск сборки в той же рабочей директории (с наполненным `.c4builder.cache`) SHALL давать дерево выходных файлов, идентичное первому прогону. Проверка выполняется на варианте `default` (механика кэша едина для всех вариантов).

#### Scenario: Второй прогон с тёплым кэшем
- **WHEN** сборка fixture варианта `default` выполняется второй раз без изменения исходников
- **THEN** выходное дерево байт-в-байт (после нормализации) совпадает с результатом первого прогона

### Requirement: Эталон обновляется только явной командой
Перезапись эталонных деревьев MUST происходить только при явном запуске режима обновления (`UPDATE_GOLDEN=1` / npm-скрипт `test:golden:update`); режим обновления SHALL регенерировать эталоны всех вариантов матрицы за один прогон. Обычный запуск тестов MUST NOT изменять эталоны.

#### Scenario: Явное обновление эталона
- **WHEN** тесты запущены в режиме обновления эталона
- **THEN** эталонные деревья всех вариантов перезаписываются текущим нормализованным выходом сборки

#### Scenario: Обычный запуск не трогает эталон
- **WHEN** тесты запущены без режима обновления
- **THEN** файлы эталонов остаются неизменными независимо от результата сравнения

### Requirement: Golden-эталон воспроизводим независимо от машины
Golden-эталон SHALL быть детерминированным и не зависеть от установленного на машине окружения. Рендер PlantUML в golden-прогонах MUST выполняться на пиновой managed-JVM из кеша jre-резолвера (Temurin, версия `TEMURIN_FEATURE`), а не на произвольной системной java: тест-хелпер резолвит кешированный JRE (при отсутствии — скачивает, минуя системную java) и передаёт его через `JAVA_HOME` запускаемому CLI. Раскладка считается Java-движком Smetana, шрифт диаграмм — вендорный; внешний graphviz не участвует. Регенерация эталона на разных машинах MUST давать идентичное дерево выходов.

#### Scenario: Регенерация на разных машинах
- **WHEN** эталон регенерируется на двух машинах с одним вендорным JAR/шрифтом
- **THEN** golden-сборка обеих машин идёт на одной и той же managed-JVM из кеша jre-резолвера и нормализованное дерево выходов идентично

#### Scenario: Локальный прогон совпадает с CI
- **WHEN** разработчик запускает `npm test` локально
- **THEN** golden-тест проходит без расхождений с эталоном, снятым на CI, независимо от того, какая системная java установлена локально

#### Scenario: Managed-JRE отсутствует и не скачивается
- **WHEN** кеш jre-резолвера пуст и скачивание JRE недоступно (нет сети/Adoptium)
- **THEN** golden-тест падает с понятной ошибкой резолва JRE, а не молча использует системную java

### Requirement: Golden-тест покрывает D2-рендер
Golden-fixture SHALL включать `.d2`-диаграмму с импортом общего `.d2`-файла, а
golden-тест MUST сравнивать её SVG-выход с эталоном наравне с PlantUML-диаграммами.
Детерминизм D2-выхода обеспечивается вшитыми шрифтами и фиксированной версией пакета
движка; vendored-шрифт для D2 не требуется.

#### Scenario: D2-диаграмма в fixture совпадает с эталоном
- **WHEN** golden-тест собирает fixture, содержащий `.d2`-диаграмму с импортом
- **THEN** её SVG (после нормализации) совпадает с закоммиченным эталоном, а
  импортированные стили присутствуют в выходе

#### Scenario: Повторный прогон D2 идентичен
- **WHEN** сборка fixture с `.d2` выполняется дважды
- **THEN** SVG-выход D2-диаграммы байт-в-байт совпадает между прогонами

### Requirement: Матрица вариантов фиксирует ветки compose-слоя
Golden-матрица SHALL включать, помимо `default`, варианты, фиксирующие альтернативные ветки формирования выхода: `links-top` (`includeLinkToDiagram=true`, `diagramsOnTop=true`, `excludeOtherFiles=true`, navigation/TOC/breadcrumbs выключены) и `embed-png` (`embedDiagram=true`, `diagramFormat=png`). Эталоны вариантов MUST фиксировать соответствующее поведение: ссылки вместо изображений и порядок «диаграммы перед текстом» (`links-top`); PNG-выход растеризацией resvg для PlantUML/D2, нативный ditaa-PNG и base64-встраивание диаграмм в md (`embed-png`).

#### Scenario: links-top — ссылки вместо картинок, диаграммы сверху
- **WHEN** собирается вариант `links-top`
- **THEN** в md-выходах диаграммы представлены ссылками (не `![diagram](...)`-изображениями), блоки диаграмм стоят перед текстом, прочие файлы (не md/puml/d2) в выход не копируются, а navigation/TOC/breadcrumbs отсутствуют

#### Scenario: embed-png — растеризация и встраивание
- **WHEN** собирается вариант `embed-png`
- **THEN** не-ditaa диаграммы (PlantUML и D2) присутствуют в выходе как PNG, полученные растеризацией SVG, ditaa — как нативный PNG, а в md-файлах диаграммы встроены как `data:image/png;base64,…`

#### Scenario: Правка compose-логики ломает соответствующий вариант
- **WHEN** поведение ветки, зафиксированной вариантом (напр. формат ссылки на диаграмму), изменено в коде без обновления эталона
- **THEN** golden-тест соответствующего варианта падает

### Requirement: Golden-тест покрывает BPMN-рендер
Golden-fixture SHALL включать `.bpmn`-диаграмму с collaboration из нескольких пулов, дорожками, промежуточным или граничным событием-таймером, message flow и кириллическими подписями. Golden-тест MUST сравнивать её SVG-выход (вариант `default`) и PNG-выход (вариант `embed-png`) с эталонами наравне с PlantUML и D2. Детерминизм обеспечивается вендорным шрифтом для метрик текста и точным пином версий пакетов раскладки и рендера.

#### Scenario: BPMN-диаграмма в fixture совпадает с эталоном
- **WHEN** golden-тест собирает fixture, содержащий `.bpmn`
- **THEN** её SVG (после нормализации) совпадает с закоммиченным эталоном

#### Scenario: Повторный прогон BPMN идентичен
- **WHEN** сборка fixture с `.bpmn` выполняется дважды
- **THEN** SVG-выход BPMN-диаграммы байт-в-байт совпадает между прогонами

#### Scenario: Обновление пакета раскладки ловится тестом
- **WHEN** версия пакета раскладки или рендера меняется и меняет координаты
- **THEN** golden-тест падает до явного переснятия эталона

## release-publishing

[Обзор](#C4-Builder)

# release-publishing

## Purpose

Требования к публикации npm-пакета через GitHub Actions: триггер строго по push git-тега версии, выбор dist-tag по семантике версии (пререлиз → `rc`, стабильная → `latest`), гейт синхронизации тега и версии из `package.json`, идемпотентность повторного запуска и сохранение provenance/trusted publishing (OIDC) без долгоживущих npm-токенов.

## Requirements

### Requirement: Публикация запускается только push-ем git-тега версии

Публикация пакета в npm SHALL выполняться GitHub Actions workflow, триггер которого — исключительно push git-тега вида `v*` (например `v0.3.0-rc.1`, `v0.3.0`), плюс ручной `workflow_dispatch`. Workflow MUST NOT публиковать пакет по событию `push` в `master` или по мержу ветки. Обычные коммиты и мержи в `master` MUST NOT приводить к публикации.

#### Scenario: Push тега версии
- **WHEN** в репозиторий пушится git-тег `v0.3.0-rc.1`
- **THEN** workflow публикации запускается и выполняет шаг публикации пакета

#### Scenario: Push/мерж в master
- **WHEN** выполнен push или мерж ветки в `master` без нового тега `v*`
- **THEN** workflow публикации не запускается и пакет не публикуется

### Requirement: Dist-tag выбирается по семантике версии

Workflow MUST определять dist-tag по версии из `package.json`: если версия — пререлиз (содержит `-`, например `0.3.0-rc.1`), публикация выполняется командой `npm publish --tag rc`; если версия стабильная (без `-`, например `0.3.0`), публикация выполняется в dist-tag `latest`. Это гарантирует, что пререлизы не смещают `latest` и не попадают в `npm install` без явного запроса.

#### Scenario: Публикация пререлиза
- **WHEN** публикуется версия `0.3.0-rc.1`
- **THEN** пакет публикуется под dist-tag `rc`, а `latest` остаётся на прежней стабильной версии

#### Scenario: Публикация стабильной версии
- **WHEN** публикуется версия `0.3.0` без суффикса пререлиза
- **THEN** пакет публикуется в dist-tag `latest`

#### Scenario: Установка релиз-кандидата
- **WHEN** пользователь выполняет `npm install @alfacapital-tech/c4builder@rc`
- **THEN** ставится последняя версия под тегом `rc`, тогда как `npm install` без тега продолжает ставить `latest`

### Requirement: Гейт синхронизации тега и версии

Перед публикацией workflow MUST проверять, что строка git-тега совпадает с версией из `package.json` в форме `v<version>`. При несовпадении workflow MUST завершаться с ошибкой и НЕ публиковать пакет — это защита от рассинхрона, при котором `npm publish` опубликовал бы версию из `package.json`, не совпадающую с намерением тега.

#### Scenario: Тег совпадает с версией
- **WHEN** тег `v0.3.0-rc.1`, а версия в `package.json` — `0.3.0-rc.1`
- **THEN** гейт проходит и workflow переходит к публикации

#### Scenario: Тег не совпадает с версией
- **WHEN** тег `v0.3.0-rc.1`, а версия в `package.json` — `0.2.25`
- **THEN** workflow завершается с ненулевым кодом и ничего не публикует

### Requirement: Идемпотентность публикации

Workflow MUST пропускать шаг публикации, если версия из `package.json` уже опубликована в npm-реестре. Повторный запуск workflow для уже опубликованной версии MUST завершаться успешно без попытки повторной публикации (без ошибки конфликта).

#### Scenario: Версия уже опубликована
- **WHEN** workflow запущен для версии, которая уже присутствует в реестре
- **THEN** шаг публикации пропускается, workflow завершается успешно

#### Scenario: Новая версия
- **WHEN** workflow запущен для версии, которой ещё нет в реестре
- **THEN** пакет публикуется под соответствующим dist-tag

### Requirement: Сохранение provenance и trusted publishing

Workflow MUST публиковать пакет с `--provenance` через OIDC trusted publishing (`permissions: id-token: write`), без хранения долгоживущих npm-токенов в секретах репозитория. Модель аутентификации MUST оставаться неизменной при переходе на тег-драйв.

#### Scenario: Публикация с provenance
- **WHEN** выполняется шаг публикации пакета
- **THEN** пакет публикуется с флагом `--provenance` и аутентификацией через OIDC, без использования статического npm-токена

## Archive

[Обзор](#C4-Builder)

- [2026-10-06-docs-site](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-docs-site/2026-10-06-docs-site)
- [2026-10-06-bpmn-diagrams](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/2026-10-06-bpmn-diagrams)
- [2026-10-03-pr8-review-fixes](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-pr8-review-fixes/2026-10-03-pr8-review-fixes)
- [2026-10-03-plugin-system](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/2026-10-03-plugin-system)
- [2026-10-03-plantuml-1-2026-8](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plantuml-1-2026-8/2026-10-03-plantuml-1-2026-8)
- [2026-10-03-offline-site-assets](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/2026-10-03-offline-site-assets)
- [2026-10-03-node-22](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-node-22/2026-10-03-node-22)
- [2026-10-03-llms-txt](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/2026-10-03-llms-txt)
- [2026-10-03-cli-fixes](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-fixes/2026-10-03-cli-fixes)
- [2026-10-03-cli-english-messages](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-english-messages/2026-10-03-cli-english-messages)
- [2026-10-03-agent-skills](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/2026-10-03-agent-skills)
- [2026-07-24-nimbus-font-system-flag](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-24-nimbus-font-system-flag/2026-07-24-nimbus-font-system-flag)
- [2026-07-09-tag-driven-rc-publish](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-09-tag-driven-rc-publish/2026-07-09-tag-driven-rc-publish)
- [2026-07-08-zod-and-deps-upgrade](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/2026-07-08-zod-and-deps-upgrade)
- [2026-07-07-ts-port-full](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-ts-port-full/2026-07-07-ts-port-full)
- [2026-07-07-build-split](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-build-split/2026-07-07-build-split)
- [2026-07-05-ts-scaffold](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/2026-07-05-ts-scaffold)
- [2026-07-05-resvg-png](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-resvg-png/2026-07-05-resvg-png)
- [2026-07-05-remove-vscode-snippets](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/2026-07-05-remove-vscode-snippets)
- [2026-07-05-remove-plantuml-version](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-plantuml-version/2026-07-05-remove-plantuml-version)
- [2026-07-05-remove-pdf](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-pdf/2026-07-05-remove-pdf)
- [2026-07-05-new-noninteractive](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-new-noninteractive/2026-07-05-new-noninteractive)
- [2026-07-05-jre-resolver](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/2026-07-05-jre-resolver)
- [2026-07-05-golden-matrix](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-golden-matrix/2026-07-05-golden-matrix)
- [2026-07-05-dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/2026-07-05-dev-toolchain)
- [2026-07-05-d2-backend](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/2026-07-05-d2-backend)
- [2026-07-04-template-offline](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-template-offline/2026-07-04-template-offline)
- [2026-07-04-plantuml-java-direct](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/2026-07-04-plantuml-java-direct)
- [2026-07-04-golden-test-ci](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/2026-07-04-golden-test-ci)

## 2026-10-06-docs-site

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="21" max="21"></progress> 21/21 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-docs-site/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-docs-site/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-docs-site/specs/specs)

## Why

Документация C4-Builder осталась от upstream: `docs/` — docsify-сайт оригинального проекта
(ссылки на `adrianvlupu`, картинки удалённого PDF-вывода, мастера и vscode-plantuml), README
в ~640 строк смешивает питч, справочник, релизный процесс и changelog, а карточка репозитория
на GitHub описывает «site, pdf» и ведёт на сайт upstream. Нигде не сказано, чем форк отличается
от оригинала (upstream не обновлялся с 2024-03): поддерживаемое продолжение, адаптированное под
агентскую разработку — детерминированный локальный рендер, `c4builder check` как обратная
связь для агента, плагины `openspec`/`openapi`. Основная аудитория — команды Альфа-Капитала
(русский), внешние пользователи — вторая (английский).

## What Changes

- **Сайт документации собирается самим c4builder** (dogfooding): исходники в `docs/`,
  сборка в CI, публикация в GitHub Pages. Сайт — живая демонстрация продукта: C4-диаграммы,
  локальный рендер, плагин `openspec`.
- **Два языка с одинаковой структурой страниц**: русский — основной, английский — полный
  перевод. Расхождение набора страниц между языками ловится в CI.
- **Лендинг** — одна статическая страница (RU/EN) в корне сайта: позиционирование форка
  («architecture-as-code, которую агент пишет, проверяет и читает»), агентский цикл
  правка → `check` → сборка, quickstart (npm/docker), ссылки на документацию, скиллы и
  `llms.txt`. Благодарность upstream и MIT сохраняются.
- **Раздел «Журнал решений»**: собственный OpenSpec-store проекта публикуется на сайте
  встроенным плагином `openspec`. Артефакты остаются на русском, в EN-версии раздел помечен
  как русскоязычный.
- **README.MD сокращается до ~100 строк**: питч, отличия от upstream, quickstart, ссылки на
  сайт (RU и EN). Справочник (команды, конфиг, выводы, плагины, Docker) переезжает на сайт.
- **Changelog выносится в `CHANGELOG.md`**; правило «строка в `## Unreleased`» и раздел
  про релизы переписываются под новый файл (`CLAUDE.md`, документация для мейнтейнеров).
- **Удаляется наследие upstream**: старый `docs/` (index.html, vendor docsify, картинки),
  раздел «Future plans», ссылки на `C4Builder-Demo` и `adrianvlupu.github.io`, в том числе
  в `template/readme.md`.
- **Карточка репозитория на GitHub** (description, homepage, topics) обновляется под новый
  сайт — внешнее действие, выполняется отдельно с подтверждением мейнтейнера.

## Capabilities

### New Capabilities
- `docs-site`: сборка сайта документации самим c4builder, паритет структуры RU/EN, лендинг,
  публикация в GitHub Pages из CI.

### Modified Capabilities
- (нет — `template/readme.md` меняет только ссылку, требования `project-template` не
  затронуты; `CHANGELOG.md` не входит в npm-пакет, `files`-whitelist из `dev-toolchain`
  не меняется)

## Impact

- `docs/` — полная замена: исходники сайта (RU, EN), лендинг, `.c4builder` сайта.
- `.github/workflows/` — новый workflow сборки и деплоя Pages (на push в `master`).
- `README.MD`, новый `CHANGELOG.md`, `CLAUDE.md` (правило changelog), `template/readme.md`.
- Настройки репозитория GitHub: включение Pages, description/homepage/topics.
- Новых npm-зависимостей нет; npm-пакет и образ не меняются.
- Связанные change'и `llms-txt` и `agent-skills`: страницы о них на сайте и в лендинге
  пишутся после их реализации (последние задачи этого change'а), остальное независимо.

## design

[Обзор](#C4-Builder)

# Design

## Context

Мотивация — в proposal.md. Ограничения, которые определяют подход:

- Проект c4builder — это папка с `.c4builder`. `rootFolder`, `distFolder`, путь конфига
  (`-c`) и `dir` плагинов разрешаются **от cwd**. Заголовок страницы в sidebar — имя
  папки как есть, порядок — порядок `readdir` (числовые префиксы `1 …` видны в заголовке,
  как в шаблоне).
- Одна сборка = один язык: i18n внутри одного проекта ядро не умеет.
- Сайт docsify офлайновый: `index.html` грузит `vendor/*` из dist, внешних CDN нет.
  Сборка пишет `.nojekyll`.
- `generateLocalImages` переименовывает старый dist в `<dist>_bk`. Если dist указать вне
  проекта, `_bk` попадёт в Pages-артефакт.
- CI уже собирает CLI (`npm run build`) и ставит Temurin 21 (`setup-java`). Юнит-тесты
  vitest (`test/*.test.mjs`) идут в обеих ногах матрицы.
- Ссылки на upstream: `src/cli/commands/help.ts` (`--docs`), `template/readme.md`,
  картинки README из `docs/images/`. Ссылки на upstream-PR в changelog — историческая
  атрибуция.

## Goals / Non-Goals

**Goals:**
- Минимум новой инфраструктуры: два c4builder-проекта, одна статическая страница, один
  workflow, один тест.
- Сайт как демонстрация продукта: собственные C4-диаграммы c4builder, локальный рендер,
  плагин `openspec`.

**Non-Goals:**
- Docsify-i18n, переключатель языка внутри docsify, общий sidebar на два языка.
- Новые GIF и скриншоты: в первой итерации их нет, демонстрацию дают живые диаграммы.
- D2 на сайте: опциональная зависимость ~60 МБ, ради сайта её в CI не ставим.
- Версионирование документации по релизам: сайт отражает `master`.
- Автоматический перевод и проверка содержательной эквивалентности RU/EN (проверяется
  только структура).

## Decisions

### D1. Два независимых проекта `docs/ru` и `docs/en`

```
docs/
  landing/        index.html (RU), en.html (EN), landing.css
  ru/             .c4builder + src/   (dist → docs/ru/dist, в .gitignore)
  en/             .c4builder + src/   (dist → docs/en/dist)
```

Каждый `.c4builder` — полный headless-конфиг (форма `new --yes`, `hasRun: true`):
`generateWEB: true`, `generateMD: false`, `generateLocalImages: true`, `diagramFormat: svg`,
`repoUrl` на GitHub-репозиторий, `homepageName` «Обзор» / «Overview», `projectName`
«C4-Builder». `distFolder: dist` внутри проекта, чтобы `_bk` не попадал в артефакт:
workflow копирует в артефакт только `dist`. В `.gitignore` добавляются `docs/*/dist*/`
и `docs/*/.c4builder.cache`.

*Альтернативы:* один проект и docsify-i18n — нужно править шаблон и sidebar ядра, а это
фича продукта, а не документации. `distFolder: ../../_site/ru` — тащит `_bk` в Pages.

### D2. Плагин `openspec` в обоих проектах

`plugins: [["openspec", {"dir": "../../openspec", "mount": "<имя раздела>"}]]`.
`mount`: «Журнал решений» (RU) и «Design log» (EN). EN-версия получает страницу-заглушку
в `src/` с пометкой «artifacts are in Russian». Пометка ставится через `.md` в корне EN,
а не в плагине, чтобы не трогать ядро. Плагин подписи сводки и таблиц уже выводит
по-английски, это допустимо для обеих версий.

### D3. Лендинг — две статические страницы и общий CSS

`docs/landing/index.html` (RU, корень сайта), `docs/landing/en.html` (EN),
`docs/landing/landing.css`. Без JS, без сборщика, без внешних шрифтов (системный стек).
Цвета на CSS-переменных, тёмная тема через `prefers-color-scheme`, вёрстка от 360px.
Содержание: позиционирование форка, агентский цикл (правка → `check` → `--site -w`),
quickstart (npm, docker), блоки «отличия от upstream» и «для агентов» (ссылки на
`llms.txt` и скиллы появляются в последней группе задач), ссылки на `ru/` и `en/`,
благодарность upstream и MIT.

*Альтернатива:* одна страница с JS-переключателем языка — меньше файлов, но нужен JS,
и на конкретный язык нельзя дать прямую ссылку.

### D4. Workflow `pages.yml`

```
on: push [master], pull_request, workflow_dispatch
job build:  checkout → setup-node 24 → npm ci --ignore-scripts → npm run build
            → setup-java temurin 21
            → (cd docs/ru && node ../../dist/index.js)  ; то же для docs/en
            → сборка _site/: landing/* → _site/, ru/dist → _site/ru, en/dist → _site/en
            → upload-pages-artifact (_site)
job deploy: needs build, if push в master или dispatch на master
            → deploy-pages (permissions pages: write, id-token: write,
              environment github-pages, concurrency group pages)
```

Сборка из `docs/<lang>` как cwd: так относительные пути `.c4builder` и `dir` плагина
работают одинаково локально (`cd docs/ru && c4builder --site -w`) и в CI. Деплой через
Actions-артефакт обходит Jekyll, `.nojekyll` не обязателен, но не мешает.

*Альтернатива:* setup-java не ставить, пусть c4builder скачает managed JRE. Выходит
медленнее и требует отдельного кэша. Для сайта пиксельный детерминизм golden не нужен.

### D5. Проверка паритета — vitest-тест

`test/docs-parity.test.mjs`. Обходит `docs/ru/src` и `docs/en/src`, нормализует каждый
путь (сегмент папки → её числовой префикс `^\d+`, имя файла `.md`/`.puml`/`.d2` →
как есть), сравнивает множества и при расхождении падает со списком путей без пары.
Папки без числового префикса — тоже ошибка: без префикса сопоставить RU и EN нельзя.
Файлы с префиксом `_` (инклюды) включаются в сравнение. Тест идёт в существующих
`npm test` / `test:unit`, workflow CI не меняется.

*Альтернатива:* отдельный скрипт и шаг CI — лишний файл и шаг ради того же.

### D6. Структура страниц (одинаковая для RU/EN)

| # | RU | EN | Источник (раздел README) |
|---|---|---|---|
| — | Обзор (`README.md` корня) | Overview | Overview, позиционирование, C4-контекст c4builder (`context.puml`) |
| 01 | Быстрый старт | Getting started | Getting started, Requirements, Installing a release candidate |
| 02 | Проект | Project | The project, The build (`_`-файлы, позиционирование диаграмм) |
| 03 | Диаграммы | Diagrams | Локальный рендер/Smetana, `plantumlServerUrl`, D2, PNG/resvg, шрифты, Validating single diagrams (`check`, pre-commit) |
| 04 | Выводы | Outputs | The output (markdown с навигацией, complete markdown, сайт, опции) |
| 05 | CLI и конфигурация | CLI & configuration | Available Commands, `jre`, справочник ключей `.c4builder` (по `--docs`) |
| 06 | Плагины | Plugins | Plugins: `openspec`, `openapi`, Writing a plugin |
| 07 | Docker и CI | Docker & CI | Docker (теги образа, использование в CI) |
| 08 | Агенты | Agents | новое: агентский цикл; `llms.txt` и скиллы — последняя группа задач |
| 09 | Разработка | Development | Releasing (rc/final), правило changelog, OpenSpec-процесс, тесты/golden, C4-контейнеры c4builder (`container.puml`) |

Не переносятся: «Future plans» (первое лицо upstream), картинки `docs/images/*`
(PDF, мастер, vscode, GitHub Pages UI), ссылка на `C4Builder-Demo`. Раздел «Generate
diagrams locally» переписывается: локальный рендер — основной режим, онлайн-сервер —
опция.

### D7. README и CHANGELOG

README (EN, ≤150 строк): название и однострочник, строка ссылок
«Документация на русском · English docs», 4–6 пунктов «чем отличается от upstream»,
quickstart (`npm i -g`, `new`, `c4builder`, `--site -w`, `check`), docker-однострочник,
ссылки (сайт, CHANGELOG, раздел Development), credits upstream и лицензия. Только
абсолютные ссылки на сайт, без относительных картинок: README уходит в npm-пакет.

`CHANGELOG.md` = секции `## Unreleased`/`## vX.Y.Z` из README без изменений, включая
ссылки на upstream-PR. В npm-пакет не входит (`files` не меняется). `CLAUDE.md`:
правило «строка в README, changelog» → «строка в `CHANGELOG.md` `## Unreleased`; при
изменении поведения — правка страницы сайта в обеих языковых версиях»; ссылка
«README Releasing» → страница сайта «Разработка».

### D8. Адрес сайта

`https://alfacapital-tech.github.io/C4-Builder/` — адрес проектного сайта GitHub Pages.
Используется в README, `--docs`, `template/readme.md`, homepage репозитория и
`homepage` в `package.json`. Свой домен не нужен.

## Risks / Trade-offs

- [Расхождение текста RU/EN при одинаковой структуре] → тест ловит только структуру.
  Правило в `CLAUDE.md`: правка страницы — в обеих версиях в том же PR.
- [Числовые префиксы видны в заголовках sidebar] → поведение ядра, как в шаблоне. Убирать
  префиксы — отдельная фича продукта, не этого change'а.
- [Pages не включён в настройках репо] → первый деплой упадёт. Задача включения Pages
  (Source: GitHub Actions) стоит до первого merge workflow и требует подтверждения
  мейнтейнера.
- [Кириллица в URL RU-страниц] → docsify и GitHub Pages работают с percent-encoding.
  Проверяется на первом деплое (задача smoke).
- [Сборка сайта удлиняет CI на PR] → отдельный workflow параллельно тестам, рендер
  ~10–20 диаграмм.

## Migration Plan

1. Включить Pages (Source: GitHub Actions). Ручной шаг мейнтейнера.
2. Merge PR: удаление `docs/`, новые исходники, workflow, README/CHANGELOG.
3. Первый деплой с `master`, smoke опубликованного сайта.
4. `gh repo edit`: description, homepage, topics. Ручной шаг с подтверждением.

Откат: revert PR. Старый `docs/` нигде не публиковался (Pages был выключен), так что
откатывать на сайте нечего.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Каркас: удаление старого docs/, проекты RU/EN, проверка паритета

- [x] 1.1 Удалить старый `docs/` целиком (`_coverpage.md`, `index.html`, `README.MD`, `images/`, `vendor/`). Проверка: `git ls-files docs/` пуст до добавления новых файлов.
- [x] 1.2 Создать `docs/ru/.c4builder` и `docs/en/.c4builder` по design D1/D2 (полный headless-конфиг, `distFolder: dist`, плагин `openspec` с `dir: ../../openspec` и mount «Журнал решений» / «Design log»), минимальный `src/README.md` в каждом. В `.gitignore` добавить `docs/*/dist*/`, `docs/*/.c4builder.cache`. Проверка: `npm run build && (cd docs/ru && node ../../dist/index.js)` и то же для `docs/en` завершаются с кодом 0 без вопросов, в `dist/` есть `index.html` и раздел журнала решений; `git status` не показывает dist/cache.
- [x] 1.3 Добавить `test/docs-parity.test.mjs` по design D5 (нормализация папок по числовому префиксу, имена `.md`/`.puml`/`.d2` как есть, папка без префикса — ошибка, сообщение со списком путей без пары). Проверка: `npx vitest run test/docs-parity.test.mjs` зелёный; временно добавленная папка `docs/ru/src/99 Тест` роняет тест с этим путём в сообщении (затем удалить).

## 2. Контент RU

- [x] 2.1 Обзор (`docs/ru/src/README.md`): что такое C4-Builder, чем форк отличается от upstream (поддержка, локальный детерминированный рендер, `check`, плагины, агентская разработка), агентский цикл, благодарность upstream. Плюс `context.puml`: C4-контекст c4builder (разработчик/агент → c4builder → PlantUML/D2, docsify-сайт, markdown, OpenSpec-store, OpenAPI-контракты) через stdlib `!include <C4/...>`. Проверка: `node dist/index.js check docs/ru/src/context.puml` → 0; сборка RU → 0, диаграмма есть на странице.
- [x] 2.2 Страницы `01 Быстрый старт` … `07 Docker и CI` по таблице design D6 из соответствующих разделов README, переведённые и актуализированные: без упоминаний PDF, vscode-plantuml, `C4Builder-Demo`, «Future plans»; локальный рендер как основной режим. Проверка: сборка RU → 0; `grep -rniE 'pdf|vscode|C4Builder-Demo|adrianvlupu' docs/ru/src` пусто.
- [x] 2.3 Страница `08 Агенты` (базовая часть): цикл правка → `c4builder check` (exit-код, формат ошибки `✗ file: line N`) → `--site -w`, pre-commit-хук, офлайн-рендер как свойство для агентов. Без `llms.txt` и скиллов: они в группе 7. Проверка: сборка RU → 0.
- [x] 2.4 Страница `09 Разработка`: сборка/тесты/golden, процесс OpenSpec (артефакты на русском, ссылка на раздел журнала решений), релизы rc/final из README «Releasing», правило `CHANGELOG.md`, `container.puml` с контейнерами c4builder (CLI, scan/compose/render, плагины, vendor). Проверка: `check` диаграммы → 0, сборка RU → 0.

## 3. Контент EN

- [x] 3.1 Перевести все страницы и диаграммы группы 2 в `docs/en/src` с теми же числовыми префиксами и именами файлов; в корень EN добавить пометку, что раздел Design log на русском (design D2). Проверка: `npx vitest run test/docs-parity.test.mjs` зелёный; сборка EN → 0; `check` всех `.puml` EN → 0.

## 4. Лендинг

- [x] 4.1 Создать `docs/landing/index.html` (RU), `docs/landing/en.html` (EN), `docs/landing/landing.css` по design D3: позиционирование, агентский цикл, quickstart (npm, docker), «отличия от upstream», ссылки на `ru/`, `en/` и вторую языковую версию лендинга, credits upstream и MIT; без JS и внешних ресурсов; токены цветов в `:root` и тёмная тема через `prefers-color-scheme`. Проверка: `grep -nE '<(script|link)[^>]+(src|href)="https?://' docs/landing/*` пусто; страница без горизонтального скролла на ширине 360px (devtools); ссылки `ru/`, `en/`, `en.html`/`index.html` работают в собранном `_site/` (задача 5.1).

## 5. Публикация

- [x] 5.1 Добавить `.github/workflows/pages.yml` по design D4 (build на PR/push/dispatch, deploy только для `master`). Проверка: локальный прогон шагов сборки (`npm run build`, сборка RU/EN, раскладка `_site/`) даёт `_site/index.html`, `_site/en.html`, `_site/ru/index.html`, `_site/en/index.html`; в PR job build зелёный, deploy пропущен. *(Локальная часть проверки выполнена; статус job'ов на PR — после push ветки.)*
- [x] 5.2 Проверить, что `pages.yml` не дублирует и не ломает `ci.yml`: тест паритета идёт в `npm test`/`test:unit`. Проверка: `npm run test:unit` зелёный; `npx biome ci .` зелёный (если biome проверяет новые файлы).

## 6. README, CHANGELOG и ссылки на upstream

- [x] 6.1 Перенести секции changelog из README в `CHANGELOG.md` без изменения текста (`## Unreleased` сверху, если секции нет — создать); добавить в `## Unreleased` строку о новом сайте документации и ссылке в `--docs`/шаблоне. Проверка: `grep -c '^## v' CHANGELOG.md` равен числу версий в старом README; в README нет `# Change log`.
- [x] 6.2 Переписать `README.MD` по design D7 (EN, ≤150 строк, ссылки на `https://alfacapital-tech.github.io/C4-Builder/ru/` и `/en/`). Проверка: `wc -l README.MD` ≤ 150; `grep -n 'docs/images\|adrianvlupu.github.io\|C4Builder-Demo' README.MD` пусто.
- [x] 6.3 Заменить адрес сайта upstream на сайт форка в `src/cli/commands/help.ts` и `template/readme.md`; `homepage` в `package.json` → адрес сайта. Проверка: `npm run build && node dist/index.js --docs | grep alfacapital-tech.github.io`; `grep -rn 'adrianvlupu.github.io' src template README.MD package.json` пусто; `npm run test:golden` не меняет эталоны (`template/readme.md` не в `src/` шаблона — если меняет, переснять и объяснить в PR).
- [x] 6.4 Обновить `CLAUDE.md` репо: правило changelog → `CHANGELOG.md`; изменение поведения → правка страницы сайта в обеих языковых версиях; ссылка «README Releasing» → страница «Разработка»; в «Структуре» — `docs/` (сайт RU/EN, лендинг). Проверка: в `CLAUDE.md` нет упоминания changelog в README.

## 7. Агентский раздел (ЗАВИСИТ от реализованных change'ей `llms-txt` и `agent-skills`)

- [x] 7.1 [после `llms-txt`] Включить вывод `llms.txt` в обоих `.c4builder` сайта; на странице `08 Агенты` (RU и EN) описать `llms.txt`/`llms-full.txt` с адресами опубликованных файлов. Проверка: сборка RU/EN → 0, в `docs/*/dist/` есть `llms.txt` и `llms-full.txt`; тест паритета зелёный.
- [x] 7.2 [после `agent-skills`] На странице `08 Агенты` (RU и EN) описать скиллы и установку `npx skills add AlfaCapital-Tech/C4-Builder`, `AGENTS.md` в шаблоне. Проверка: сборка RU/EN → 0; команда установки совпадает с README скиллов.
- [x] 7.3 Добавить на лендинг (RU и EN) блок «Для агентов» со ссылками на `llms.txt` и раздел скиллов; добавить строку в README. Проверка: ссылки ведут на существующие пути в `_site/`; README ≤ 150 строк.

## 8. Ручные шаги мейнтейнера (требуют подтверждения, вне субагента)

- [x] 8.1 Включить GitHub Pages с источником «GitHub Actions» (`gh api -X POST repos/AlfaCapital-Tech/C4-Builder/pages -f build_type=workflow`) и выставить переменную репо `PAGES_ENABLED=true` (`gh variable set PAGES_ENABLED --body true`) — без неё job `deploy` пропускается. Выполнено 2026-10-05 после разрешения админов (ATD-16611). Проверка: `gh api repos/AlfaCapital-Tech/C4-Builder/pages` возвращает `build_type: workflow`.
- [x] 8.2 После первого деплоя — smoke опубликованного сайта: корень (RU-лендинг), `en.html`, `ru/`, `en/`, страница с кириллическим URL, раздел журнала решений, в devtools нет запросов к внешним доменам. Проверка: все пункты открываются без 404.
- [x] 8.3 Обновить карточку репозитория: `gh repo edit AlfaCapital-Tech/C4-Builder --description "<новое описание без pdf>" --homepage https://alfacapital-tech.github.io/C4-Builder/ --add-topic c4-model,plantuml,architecture-as-code,docsify,ai-agents`. Проверка: `gh api repos/AlfaCapital-Tech/C4-Builder --jq '.description,.homepage,.topics'`.

## specs

[Обзор](#C4-Builder)

- [docs-site](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-docs-site/specs/docs-site/docs-site)

## docs-site

[Обзор](#C4-Builder)

# Spec Delta

## Purpose

Публичный сайт документации C4-Builder: собирается самим c4builder из исходников
репозитория, существует на русском и английском с одинаковой структурой, имеет лендинг
и публикуется в GitHub Pages из CI. README и `c4builder --docs` ведут на этот сайт.

## ADDED Requirements

### Requirement: Сайт собирается c4builder из того же коммита
Сайт документации SHALL собираться CLI c4builder, скомпилированным из того же коммита
репозитория, а не опубликованной версией пакета. Сборка MUST выполняться в CI на каждый
pull request и на каждый push в `master`. Ошибка сборки любой языковой версии, включая
ошибку рендера диаграммы, MUST давать красный статус проверки.

#### Scenario: Сборка на pull request
- **WHEN** открыт pull request, меняющий исходники сайта или код CLI
- **THEN** CI собирает обе языковые версии сайта текущим кодом CLI и не публикует результат

#### Scenario: Битая диаграмма в исходниках сайта
- **WHEN** в исходниках сайта есть `.puml`, который не компилируется
- **THEN** проверка сборки сайта завершается красным статусом

### Requirement: Публикация только из master
Сайт SHALL публиковаться в GitHub Pages только по push в `master` (или ручному запуску
workflow на `master`). Pull request'ы и другие ветки MUST NOT менять опубликованный сайт.

#### Scenario: Merge в master
- **WHEN** изменения слиты в `master` и сборка сайта прошла
- **THEN** опубликованный сайт обновляется до состояния этого коммита

#### Scenario: Pull request
- **WHEN** CI отработал на pull request
- **THEN** опубликованный сайт остаётся прежним

### Requirement: Раскладка публикации
Опубликованный сайт SHALL содержать в корне лендинг на русском (`index.html`) и его
английскую версию (`en.html`), документацию на русском под `ru/` и на английском под
`en/`. Каждая страница лендинга MUST ссылаться на обе языковые версии документации и на
другую языковую версию лендинга. Лендинг и сайт документации MUST NOT загружать ресурсы
с внешних CDN: все скрипты, стили и шрифты отдаются с самого сайта.

#### Scenario: Корень сайта
- **WHEN** пользователь открывает корень опубликованного сайта
- **THEN** он видит русский лендинг со ссылками на `ru/`, `en/` и `en.html`

#### Scenario: Нет внешних ресурсов
- **WHEN** лендинг или страница документации загружаются в браузере
- **THEN** все запросы скриптов, стилей и шрифтов идут на домен сайта

### Requirement: Паритет структуры RU и EN
Исходники русской и английской документации SHALL иметь одинаковую структуру: каждой
папке-странице одной версии MUST соответствовать папка с тем же числовым префиксом
порядка на том же уровне в другой версии, а набор имён `.md`, `.puml` и `.d2` файлов в
соответствующих папках MUST совпадать. Расхождение MUST давать красный статус CI с
перечнем путей без пары.

#### Scenario: Страница добавлена только в одну версию
- **WHEN** в русской документации добавлена папка-страница без английской пары
- **THEN** CI падает и называет путь страницы без пары

#### Scenario: Структура совпадает
- **WHEN** обе версии содержат одинаковые по порядку папки и одинаковые имена файлов
- **THEN** проверка паритета проходит, независимо от различий в названиях папок

### Requirement: Журнал решений на сайте
Обе языковые версии сайта SHALL содержать раздел с OpenSpec-store репозитория (активные
change'и, спеки, архив), собранный встроенным плагином `openspec`. Английская версия MUST
предупреждать, что артефакты раздела написаны на русском.

#### Scenario: Новый change в репозитории
- **WHEN** в `openspec/changes/` слит новый change и сайт пересобран
- **THEN** change виден в разделе журнала решений обеих языковых версий

### Requirement: README как точка входа
`README.MD` SHALL содержать краткое описание проекта, отличия от upstream, quickstart и
ссылки на обе языковые версии сайта, не более 150 строк. Справочник по командам, конфигу,
выводам и плагинам MUST находиться на сайте, а не в README. README MUST NOT ссылаться на
файлы, отсутствующие в репозитории.

#### Scenario: Читатель на GitHub или npm
- **WHEN** пользователь открывает README на странице репозитория или пакета
- **THEN** он видит quickstart и ссылки на русскую и английскую документацию, без битых картинок

### Requirement: Журнал изменений в отдельном файле
История изменений SHALL вестись в `CHANGELOG.md` в корне репозитория: секция
`## Unreleased` сверху, далее версии `## vX.Y.Z` от новых к старым. README MUST NOT
содержать журнал изменений.

#### Scenario: Пользовательское изменение в PR
- **WHEN** PR меняет поведение CLI
- **THEN** строка об изменении добавляется в `## Unreleased` файла `CHANGELOG.md`

### Requirement: Ссылки на документацию ведут на сайт форка
`c4builder --docs` и `readme.md` шаблона `c4builder new` SHALL ссылаться на сайт
документации форка. Ссылки на сайт upstream (`adrianvlupu.github.io`) MUST отсутствовать
в коде CLI, шаблоне и README. Благодарности upstream и ссылки на исторические PR в
`CHANGELOG.md` допустимы.

#### Scenario: Справка CLI
- **WHEN** пользователь запускает `c4builder --docs`
- **THEN** в выводе указан адрес сайта документации форка

## 2026-10-06-bpmn-diagrams

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="18" max="18"></progress> 18/18 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/specs/specs)

# Proposal

## Why

Команды, которые документируют свою предметную область в c4builder (например, ЭДО с процессами
по паевым фондам: клиент → банк-агент → управляющая компания → спецдепозитарий → регистратор),
просят BPMN-диаграммы. Им нужна привычная бизнес-читателю нотация: события, шлюзы с маркерами,
типы задач, горизонтальные пулы и дорожки, message flow. Это документация, не исполняемые
процессы. UML-activity со swimlanes из PlantUML не подходит: дорожки там только вертикальные, а
событий, пулов и message flow в BPMN-смысле нет.

Код в этих командах пишут агенты. Поэтому источник должен быть текстом, который агент пишет
без координат, а сборка — раскладывать и проверять его сама. Агент не умеет хорошо расставлять
фигуры, зато хорошо пишет BPMN 2.0 XML и исправляет ошибки по точной обратной связи.

## What Changes

- **Новый тип диаграмм `.bpmn`** наравне с `.puml` и `.d2`, движок выбирается по расширению.
  Источник — семантический BPMN 2.0 XML: процессы, пулы (collaboration), дорожки (laneSet),
  события, задачи, шлюзы, sequence/message flow. Координаты (BPMN DI) в источнике не нужны: если
  они есть, игнорируются.
- **Автоматическая раскладка при сборке:** горизонтальные пулы и дорожки, поток слева направо,
  message flow между пулами.
- **Рендер в SVG без браузера и без сети** в стандартной нотации bpmn.io. Вид детерминирован:
  метрики текста считаются по вендорному шрифту. PNG получается существующей растеризацией SVG.
- **Семантическая валидация (lint)** при сборке и в `c4builder check`. Проверяются
  несвязанные узлы, отсутствие start/end, узел вне дорожки, sequence flow через границу пула и
  т.п. Сообщения ссылаются на id элемента, чтобы агент исправил ошибку без человека.
- **Шаблон `new`** получает пример BPMN-процесса (пулы, дорожки, таймер, message flow,
  кириллица). Он же — golden-fixture рендера.
- **Агентская поддержка:** справочник `references/bpmn.md` в скилле `c4builder` (конвенции:
  без DI, дорожка — роль, пул — внешняя организация) и страницы сайта документации. Это делается
  с учётом вмерженных `agent-skills` и `docs-site`.
- Зависимости BPMN-движка опциональные и загружаются только при наличии `.bpmn` в проекте, как
  у D2. Проекты без `.bpmn` не меняются.

## Capabilities

### New Capabilities
- `bpmn-diagrams`: формат источника `.bpmn`, раскладка, рендер, валидация в сборке и
  `c4builder check`, ленивая загрузка зависимостей.

### Modified Capabilities
- `diagram-rendering`: выбор движка по расширению включает `.bpmn` (третий бэкенд рендера).
- `regression-testing`: golden-fixture покрывает BPMN-рендер (SVG и PNG).
- `project-template`: шаблон демонстрирует BPMN-процесс; требование об офлайн-сборке
  формулируется для всех локальных движков, а не только PlantUML JAR.

## Impact

- **Код:**
  - `src/core/scan/tree.ts` (реестр `DIAGRAM_ENGINES`);
  - новый `src/core/render/bpmnrenderer.ts`;
  - `src/core/render/diagrams.ts` (ветка движка, ключ кэша);
  - `src/cli/commands/check.ts`.
- **Зависимости (optional, точный пин):** `bpmn-js`, `bpmn-auto-layout` (2.0.0-alpha), `bpmnlint`,
  `bpmn-moddle`, `jsdom`. Размер установки растёт, но для проектов без `.bpmn` не загружается.
- **Шаблон и тесты:** `template/src/5 BPMN Example/`, эталоны golden `default` и `embed-png`,
  юнит-тесты нормализации и правил lint.
- **Документация:** `CHANGELOG.md`, страницы сайта `docs/ru` и `docs/en`, `skills/c4builder/references/bpmn.md`.
- **Зависит от change'а `node-22`:** зависимости требуют Node 22. Связан с `llms-txt`: в
  `llms-full.txt` исходник `.bpmn` вставляется как fence `xml`.
- Внешних сервисов и браузера нет. Арх-репа без `.bpmn` не затронута.

## design

[Обзор](#C4-Builder)

# Design

## Context

Мотивация — см. proposal.md. Исследование (2026-10, прототипы на процессах ПИФ: 5 дорожек +
black-box пул, 23 узла; 3 пула, 37 узлов, 4 message flow) дало такую картину.

**Раскладка с горизонтальными дорожками — самое слабое звено экосистемы.**
- `bpmn-auto-layout` 1.x (bpmn-io) раскладывает только первого участника, пулы и дорожки
  игнорирует.
- 2.0.0-alpha.0–2 (июль 2026, тег `next`) — новый семантический layered-движок: пулы,
  вложенные горизонтальные дорожки, message flow, boundary events, `warnings`, детерминированный
  вывод (проверено побайтно). API — `layoutProcess(xml) → { xml, warnings }`.
  - Открытые дефекты: плотные циклы (#150), наложения рёбер (#147/#148), TypeError на
    нестандартной модели (#155) и **молчаливая потеря элементов (#154)**: на 8 из 23
    эталонных моделей часть узлов и рёбер остаётся без DI-фигур при пустых `warnings`
    (худший случай — 52 из 107 элементов, 3 пула из 4).
- Альтернативы:
  - `bpmn-elk-layout` снят с npm 29.09.2026 — ребрендинг в `tramito-layout` (Apache-2.0,
    движок коммерческого сервиса, один автор), на тестах раскладывает хуже;
  - `bpmn-auto-layout-extended` — форк одного автора;
  - elkjs, maxGraph и Java-раскладчики горизонтальные дорожки не умеют.

**Рендер.**
- Все известные docs-as-code инструменты (Kroki, asciidoctor-diagram, MkDocs-плагины)
  рендерят BPMN в headless Chromium, нам это запрещено.
- `bpmn-js` Viewer работает под jsdom без правки исходников:
  - текст меряется только через `canvas.getContext('2d').measureText`
    (`diagram-js/lib/util/Text.js`);
  - `getBBox` нужен только `saveSVG` для viewBox;
  - нужны заглушки SVGMatrix/SVGTransformList.
  - Прототип на Nimbus Sans дал побайтно одинаковые SVG и PNG в трёх прогонах.
- Лицензия bpmn-js — MIT + условие о водяном знаке. Для экспортированного SVG оно не действует:
  ответ мейнтейнера bpmn-io (forum.bpmn.io, 19.08.2026, «Our license doesn't require the
  watermark on the exported diagrams»), после него Kroki закрыл yuzutech/kroki#2140.
- Особенности `saveSVG`:
  - id маркеров случайные (`marker-<random>`);
  - `url('#…')` пишется в кавычках, а resvg такие ссылки игнорирует, и стрелки пропадают.

**Источник и валидация.**
- По исследованиям (arXiv 2507.11356, 2509.24592) BPMN XML без DI на 64–70% короче полного без
  потери качества генерации. Сильные модели правят XML почти так же точно, как JSON.
- Бенчмарков по дорожкам нет — качество проверяем своим eval.
- Цикл исправления по ошибкам валидатора сводит сбои к нулю (ProMoAI, в среднем 1,35 итерации).
- `bpmnlint` 11.x (MIT, чистый Node) линтует семантическую модель и сообщает id элемента. Но он,
  как и раскладчик, опирается на `incoming`/`outgoing`: если агент пишет только
  `sourceRef`/`targetRef`, получается каскад ложных ошибок (57 на тестовой модели).

**Устройство c4builder.**
- Движки — реестр `DIAGRAM_ENGINES` (`src/core/scan/tree.ts`).
- Рендер и кэш — `src/core/render/diagrams.ts`. Ключ кэша — префикс движка с версиями, как
  у D2.
- Образец ленивой опциональной зависимости — `d2renderer.ts`.
- `check` — таблица `CHECKERS` в `src/cli/commands/check.ts`.
- PNG — растеризация SVG через resvg (обычная зависимость).
- Плагины добавлять движки не умеют, это сознательная граница контракта (`plugins/types.ts`).

## Goals / Non-Goals

**Goals:**
- Агент пишет `.bpmn` без координат и за один цикл `check` получает либо картинку, либо точные
  ошибки с id элементов.
- Привычная BPMN-нотация с горизонтальными пулами и дорожками в сайте, md и PNG.
- Детерминизм и офлайн на уровне PlantUML/D2: golden-тесты, без браузера и сети.

**Non-Goals:**
- Ручная доводка раскладки (учёт DI из источника), выдача `.bpmn` с DI для внешних редакторов.
- Интерактивный просмотрщик (zoom/pan) на сайте, fence ```` ```bpmn ```` в артефактах OpenSpec.
- Исполняемый BPMN, расширения Camunda/Flowable, проектный `.bpmnlintrc`.
- Свой раскладчик или свой рендерер.

## Decisions

1. **Источник — стандартный BPMN 2.0 XML, а не свой DSL.**
   - Модели знают стандарт.
   - Файл открывается любым BPMN-инструментом.
   - Валидатор и раскладчик работают с XML напрямую.
   - *Альтернатива* — компактный YAML/JSON с компиляцией в XML (Stieges/bpmn-generator,
     BPMN Assistant): примерно на 75% меньше выходных токенов, но это свой язык на поддержке,
     которого модели не знают. Выигрыш заметен только на слабых моделях.

2. **DI из источника всегда отбрасывается, раскладка всегда автоматическая.**
   - Нет проблемы устаревшего DI: агент добавил узел в файл с ручными координатами, а фигуры
     у узла нет.
   - Нет двух режимов поведения.
   - *Альтернатива* «полный DI — берём, неполный — раскладываем заново» добавляется позже без
     ломки, если раскладчик где-то не справится. Сейчас у этого нет потребителя.

3. **Конвейер одного файла** (модуль `bpmnrenderer.ts`, общий для сборки и `check`):
   1. **Разбор и нормализация** через `bpmn-moddle`:
      - `incoming`/`outgoing` восстанавливаются из `sourceRef`/`targetRef`;
      - `definitions.diagrams` очищается;
      - висячие ссылки и ошибки импорта превращаются в ошибку «файл: id: причина».
   2. **Валидация** через `bpmnlint` по нормализованной модели (решение 4). Ошибки
      прерывают конвейер, предупреждения уходят в лог.
   3. **Раскладка:** `layoutProcess(xml)` из `bpmn-auto-layout`. Исключение превращается в
      ошибку «файл: раскладка не удалась: <сообщение>», `warnings` — в предупреждения.
   4. **Рендер:**
      - `bpmn-js` Viewer в изолированном окне jsdom: production-бандл
        `bpmn-viewer.production.min.js` выполняется в окне, глобальные объекты процесса Node не
        трогаются;
      - `importXML` → `saveSVG`.
   5. **Постобработка SVG:**
      - viewBox считается из DI через `elementRegistry` (без `getBBox`), с отступом;
      - `marker-<random>` переименовываются в `marker-<n>` по порядку появления;
      - кавычки в `url('#…')` снимаются.
   6. **PNG** — штатная растеризация (`pngraster.ts`).

   Окно jsdom одно на процесс сборки, закрывается в `teardown` (как воркер D2), чтобы CLI
   завершался.

4. **Набор правил валидации фиксирован и встроен в c4builder.**
   - Берётся `bpmnlint:recommended` без `no-bpmndi`: DI в источнике не нужен.
   - Плюс плагин c4builder:
     - `lane-membership` (error): если у процесса есть дорожки, каждый flow node ровно в
       одной;
     - `sequence-flow-in-pool` (error, с подсказкой «используйте message flow»);
     - `message-flow-between-pools` (error);
     - `gateway-flow-labels` (warning): у исходящих потоков XOR/inclusive-шлюза с несколькими
       выходами есть подписи.
   - Правила грузятся статическим резолвером, без поиска пакетов `bpmnlint-plugin-*` в
     `node_modules` проекта.
   - *Альтернатива* — проектный `.bpmnlintrc`: гибче, но ломает одинаковость «что проверил
     агент = что проверит CI» и добавляет конфиг-поверхность. Добавим, если команды попросят.

5. **Метрики текста — вендорный Nimbus Sans через resvg, который уже в зависимостях.**
   - Полифил `measureText` в окне jsdom считает ширину строки рендером текста в resvg
     (`getBBox`, ~0,17 мс на замер) или по advance-ширинам шрифта.
   - `textRenderer` настраивается на `Nimbus Sans`.
   - Режим системных шрифтов на BPMN не влияет (как и на D2): детерминизм важнее.
   - В браузере без Nimbus SVG показывается метрически совместимым Helvetica/Arial.
   - *Альтернатива* `opentype.js` — ещё одна зависимость ради того, что resvg уже умеет.
     Расхождение между ними на прототипе меньше 1 px.

6. **Зависимости — `optionalDependencies` с точным пином, ленивая загрузка.**
   - Пакеты: `bpmn-js`, `bpmn-moddle`, `bpmnlint`, `bpmn-auto-layout@2.0.0-alpha.N` (точная
     последняя alpha на момент реализации), `jsdom@29`.
   - jsdom 29 (`^20.19 || ^22.13 || >=24`) покрывает границу `>=22.17` из change'а
     `node-22`. jsdom 30 требует `^22.22.2 || ^24.15`: переход на него — вместе с будущим
     подъёмом `engines`.
   - Загрузка — при первом `.bpmn`. Нет пакетов — ошибка с подсказкой
     `npm i -g @alfacapital-tech/c4builder` без `--omit=optional` (как у D2).
   - Ключ кэша: `bpmn\0<версии bpmn-js, bpmn-auto-layout, bpmnlint>\0fmt=<svg|png>` + содержимое.

7. **Реестр и вывод.**
   - `{ ext: '.bpmn', engine: 'bpmn', remoteRender: false }` в `DIAGRAM_ENGINES`.
   - Выход `<имя>.svg`/`.png` по имени файла; ссылки в md — штатные.
   - `check`: `'.bpmn'` в `CHECKERS` и в тексте подсказки по расширениям. Сообщение об ошибке
     валидации — `✗ <файл>: <id> [<правило>] <описание>`, по строке на нарушение.
   - В `llms-full.txt` (change `llms-txt`) исходник вставляется fence'ом с языком `xml`.
     Локальных зависимостей у `.bpmn` нет, приложение include-файлов не пополняется.

8. **Пример в шаблоне — `template/src/5 BPMN Example/`.** Тема продолжает демо «Internet
   Banking System»: «Открытие счёта».
   - Пулы: «Банк» с дорожками «Клиент», «Фронт-офис», «Бэк-офис» и внешний «Бюро кредитных
     историй» (black-box).
   - Есть XOR с подписанными ветками, граничный таймер на задаче, message flow.
   - md-страница объясняет, что пишется только семантика.
   - Пример же — golden-fixture и образец для скилла. Внутренних процессов компании в
     публичном репозитории нет.

## Risks / Trade-offs

- **Раскладчик в alpha:** API и координаты меняются между версиями, есть известные дефекты.
  - Точный пин; golden ловит любой сдвиг.
  - Исключение превращается в понятную ошибку с путём файла.
  - Защита от #154: после раскладки каждый `FlowNode`, `SequenceFlow`, `MessageFlow`,
    `Participant` и `Lane` процесса обязан иметь `BPMNShape`/`BPMNEdge` в DI; иначе — ошибка
    «файл: раскладка потеряла N элементов: id1, id2…», а не урезанная схема на сайте.
  - Найденные на eval дефекты — upstream issues.
  - Запасные пути: вендорить зафиксированную версию (MIT) или перейти на
    `tramito-layout`, интерфейс которого тот же «XML → XML с DI» (перед использованием сверить
    лицензию зависимости `elkjs`: EPL-2.0 / GPL-3.0). `bpmn-auto-layout-extended` и прочие
    форки заброшены (ресёрч 2026-10-03), зависимость из git-ветки upstream не берём — плохо
    ставится у пользователей пакета; ждём alpha.3 или вендорим сборку.
- **Полифилы jsdom ломаются при обновлении bpmn-js** → точный пин; обновление — отдельным PR с
  переснятием golden. Крайний вариант — свой рендерер по DI (1–1,5 тыс. строк), сейчас не
  делаем.
- **Обойти неудачную раскладку конкретной диаграммы нечем:** DI игнорируется. Можно
  переструктурировать модель (вынести подпроцесс, разбить на обзор и детализацию — это пишем в
  скилл) или дождаться режима учёта DI (Non-Goal сейчас).
- **Качество моделей по дорожкам не измерено** → eval на 2–3 реальных процессах ЭДО до
  объявления фичи готовой (tasks). Процессы и картинки остаются вне публичного репозитория,
  в репозиторий попадают только выводы и issues.
- **Установка `npm i -g` тяжелеет** (jsdom, bpmn-js) для всех, включая проекты без BPMN →
  прецедент D2 (~60 МБ) уже принят; `--omit=optional` оставляет только ядро.
- **Широкие диаграммы на 40+ узлов плохо читаются картинкой на сайте** → в скилле: обзорный
  процесс плюс детализация подпроцессов. Интерактивный просмотрщик — следующий шаг, если
  понадобится.

## Migration Plan

Аддитивно: проекты без `.bpmn` не меняются, golden-эталоны существующих вариантов меняются
только добавлением BPMN-раздела шаблона. Порядок: после `node-22`; задачи по скиллу и сайту —
после вмерживания `agent-skills` и `docs-site`. Откат — revert PR (раздел шаблона, движок и
зависимости уходят вместе).

## tasks

[Обзор](#C4-Builder)

# Tasks

Порядок: после реализации change'а `node-22` (jsdom 29 и раскладчик требуют Node 22).

## 1. Движок `.bpmn`: зависимости и каркас

- [x] 1.1 `optionalDependencies` с точным пином (design §6): `bpmn-js`, `bpmn-moddle`, `bpmnlint`, `bpmn-auto-layout` (последняя `2.0.0-alpha.N`), `jsdom@29`. Проверка: `npm ci` ставит их; `npm ls bpmn-auto-layout jsdom` показывает точные версии; `npm audit --audit-level=high` зелёный
- [x] 1.2 `src/core/scan/tree.ts`: `{ ext: '.bpmn', engine: 'bpmn', remoteRender: false }` в `DIAGRAM_ENGINES`; новый `src/core/render/bpmnrenderer.ts` с ленивой загрузкой пакетов по образцу `d2renderer.ts` (нет пакета → ошибка с подсказкой установки без `--omit=optional`) и `teardownBpmn()`; ветка движка и ключ кэша `bpmn\0<версии>\0fmt=…` в `src/core/render/diagrams.ts` (design §6–7). Проверка: тест рядом с D2-тестами ленивой загрузки (`test/diagram-deps.test.mjs` или новый) — проект без `.bpmn` не загружает пакеты BPMN; подмена резолва пакета на отсутствующий даёт понятную ошибку; смена версии в ключе кэша инвалидирует диаграмму

## 2. Нормализация и валидация

- [x] 2.1 Нормализация через `bpmn-moddle` (design §3.1): восстановление `incoming`/`outgoing` из `sourceRef`/`targetRef`, очистка `definitions.diagrams`, ошибки импорта и висячие ссылки → «файл: id: причина». Проверка: юнит-тест на фикстурах — модель только со `sourceRef`/`targetRef` даёт полные `incoming`/`outgoing`; модель с произвольным DI после нормализации без DI; ссылка на несуществующий id → ошибка с этим id
- [x] 2.2 Валидация `bpmnlint` (design §4): `recommended` без `no-bpmndi` + встроенный плагин c4builder с правилами `lane-membership`, `sequence-flow-in-pool`, `message-flow-between-pools` (error) и `gateway-flow-labels` (warning), статический резолвер правил. Ошибки прерывают конвейер, предупреждения — в лог. Проверка: юнит-тесты по фикстуре-нарушителю на каждое правило (id элемента и имя правила в сообщении) и на корректную модель без нарушений; фикстура «только `sourceRef`/`targetRef`» не даёт ни одной ошибки `no-disconnected`/`no-implicit-*`

## 3. Раскладка и рендер

- [x] 3.1 Раскладка `layoutProcess` (design §3.3): исключение → «файл: раскладка не удалась: …», `warnings` → предупреждения. Проверка: юнит-тест — фикстура с двумя пулами, тремя дорожками и message flow даёт DI, где каждый узел внутри полосы своей дорожки (сравнение bounds), повторный вызов возвращает идентичный XML; искусственно падающий раскладчик (мок) даёт сообщение с путём файла
- [x] 3.1a Защита от молчаливой потери элементов (upstream #154, design «Risks»): после `layoutProcess` сверить, что у каждого `FlowNode`/`SequenceFlow`/`MessageFlow`/`Participant`/`Lane` есть фигура в DI, иначе ошибка «файл: раскладка потеряла N элементов: id…». Проверка: юнит-тест с моком раскладчика, выкидывающим одну фигуру, — ошибка с путём файла и id; на фикстуре шаблона ошибки нет
- [x] 3.2 Рендер в jsdom (design §3.4, §5): одно окно на процесс, production-бандл Viewer выполняется в окне, полифилы `measureText` (Nimbus Sans через resvg), SVGMatrix/TransformList; `textRenderer` на `Nimbus Sans`; закрытие окна в `teardownBpmn()`. Проверка: тест — SVG содержит фигуры пулов/дорожек, маркер таймера и message flow; кириллица из подписей присутствует в SVG; процесс CLI завершается после сборки (spawn с таймаутом)
- [x] 3.3 Постобработка SVG (design §3.5): viewBox из DI, `marker-<n>` по порядку, `url(#…)` без кавычек; PNG — штатная растеризация. Проверка: два рендера одного файла побайтно равны; в SVG нет `marker-` со случайным суффиксом и `url('#`; PNG-растеризация показывает стрелки (тест на непустые пиксели в области наконечника или сравнение с эталоном из группы 5)

## 4. `c4builder check`

- [x] 4.1 `src/cli/commands/check.ts`: `'.bpmn'` в `CHECKERS` (тот же конвейер в память), подсказка по расширениям включает `.bpmn`, формат ошибок `✗ <файл>: <id> [<правило>] <описание>` по строке на нарушение, предупреждения не меняют код выхода; `teardownBpmn()` в конце. Проверка: `test/check.test.mjs` — корректная модель → код 0; несвязанная задача → код 1 и строка с id и `no-disconnected`; только warning → код 0 и предупреждение в выводе

## 5. Шаблон и golden

- [x] 5.1 `template/src/5 BPMN Example/` (design §8): `account-opening.bpmn` без DI (пул «Банк» с дорожками «Клиент», «Фронт-офис», «Бэк-офис», black-box пул «Бюро кредитных историй», XOR с подписанными ветками, граничный таймер, message flow, русские подписи) и md-страница о том, что пишется только семантика. Проверка: `node dist/index.js check "template/src/5 BPMN Example/account-opening.bpmn"` → код 0; сборка шаблона рендерит SVG
- [x] 5.2 Переснять golden `default` и `embed-png` (`UPDATE_GOLDEN=1`), добавить в `test/golden.test.mjs` проверки по образцу D2: `5 BPMN Example/account-opening.svg` в `default`, `.png` вместо `.svg` в `embed-png`, кириллица и горизонтальные полосы дорожек в SVG. Проверка: `npm run test:golden` зелёный; diff эталонов затрагивает только новый раздел, sidebar/навигацию и complete-документы; повторный прогон без `UPDATE_GOLDEN` зелёный

## 6. `llms-full.txt`

- [x] 6.1 `src/core/compose/markdown.ts`: для `engine === 'bpmn'` язык fence — `xml` (сейчас fence берёт `diagram.engine` как язык), сбор include-зависимостей пропускает `.bpmn` (у BPMN их нет; сейчас ветка `else` гоняет PlantUML-поиск `!include`). Проверка: `test/llms.test.mjs` — исходник `.bpmn` в `llms-full.txt` стоит в fence `xml` и не попадает в `## Included files`; golden `default` (`llms-full.txt`) переснят в 5.2

## 7. Eval на реальных процессах

- [x] 7.1 С командой ЭДО: 2–3 реальных процесса по паевым фондам описываются агентом со скиллом `c4builder` (после 8.1) в приватном проекте — цикл `check` → сборка. Фиксируем: число итераций до зелёного `check`, ошибки моделирования (недостающие шлюзы, узлы не в той дорожке), дефекты раскладки. Процессы и картинки в публичный репозиторий не попадают. Проверка: краткий отчёт с выводами (без внутренних данных) в описании PR; дефекты раскладчика заведены issues в `bpmn-io/bpmn-auto-layout` с обезличенными минимальными моделями. Выполнено 2026-10-06 в сокращённом объёме: мини-проверка мейнтейнера, блокирующих дефектов нет
- [x] 7.2 По итогам eval: правки конвенций скилла и/или правил lint; если раскладка неприемлема на типовом процессе — решение (вендорить версию / перейти на альтернативу / режим учёта DI) фиксируется в design.md до мержа. Проверка: отчёт 7.1 не содержит блокирующих дефектов либо решение записано. Выполнено 2026-10-06: правки по итогам мини-проверки не потребовались

## 8. Актуализация

- [x] 8.1 Скилл: новый `skills/c4builder/references/bpmn.md` (английский; источник без DI, дорожка — роль внутри организации, пул — внешняя организация, между пулами только message flow, подписи веток XOR, обзор + детализация вместо гигантской диаграммы, цикл `c4builder check file.bpmn`, разбор формата ошибок, минимальный пример); `skills/c4builder/SKILL.md` — `.bpmn` в `description` и в цикле check, ссылка на reference с условием загрузки; `references/diagrams.md` — третий бэкенд по расширению. Проверка: `npx vitest run test/skills.test.mjs` зелёный
- [x] 8.2 `template/AGENTS.md`: `.bpmn` среди типов диаграмм и в команде `check`. Проверка: `test/skills.test.mjs` зелёный
- [x] 8.3 `CHANGELOG.md` (`## Unreleased`): строка о BPMN-диаграммах, опциональных зависимостях и `--omit=optional`; страницы сайта `docs/ru` и `docs/en` о BPMN (формат источника, раскладка, `check`, конвенции) с одинаковой структурой; README — только если в нём перечислены поддерживаемые типы диаграмм. Проверка: проверка паритета RU/EN из `docs-site` зелёная; ревью глазами
- [x] 8.4 Интеграция: `npm test`, `npm run check` зелёные; `npm pack --dry-run` не содержит лишнего; установка с `--omit=optional` в чистый каталог → сборка шаблона падает с понятной подсказкой на `.bpmn`; Docker-образ (`docker build`) собирает шаблон с BPMN без сети. Проверка: CI зелёный, вывод ручных проверок — в описании PR

## specs

[Обзор](#C4-Builder)

- [bpmn-diagrams](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/specs/bpmn-diagrams/bpmn-diagrams)
- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/specs/diagram-rendering/diagram-rendering)
- [project-template](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/specs/project-template/project-template)
- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-06-bpmn-diagrams/specs/regression-testing/regression-testing)

## bpmn-diagrams

[Обзор](#C4-Builder)

# Spec Delta

## Purpose

BPMN-диаграммы процессов как документация: агент пишет семантический BPMN 2.0 XML без координат, сборка валидирует его, раскладывает с горизонтальными пулами и дорожками и рендерит в стандартной нотации офлайн и детерминированно.

## ADDED Requirements

### Requirement: Источник BPMN — семантический XML без координат
Сборка SHALL принимать файлы `.bpmn` с BPMN 2.0 XML. Достаточно семантической части: процессы, collaboration с участниками (пулами), laneSet с дорожками, события, задачи, шлюзы, подпроцессы, sequence flow и message flow. Секция диаграммы (BPMN DI, `bpmndi:BPMNDiagram`) MUST NOT требоваться; если она присутствует, сборка MUST игнорировать её и раскладывать диаграмму автоматически. Невалидный XML или неизвестный BPMN-элемент MUST давать ошибку с путём файла и описанием причины.

#### Scenario: Файл без координат
- **WHEN** в проекте есть `.bpmn` только с семантической частью (без `bpmndi:BPMNDiagram`)
- **THEN** сборка рендерит диаграмму без ошибок

#### Scenario: Координаты в источнике игнорируются
- **WHEN** `.bpmn` содержит секцию BPMN DI с произвольными координатами
- **THEN** выход совпадает с выходом того же файла без секции DI

#### Scenario: Битый XML
- **WHEN** `.bpmn` не является корректным XML или ссылается на несуществующий id
- **THEN** сборка падает с сообщением, содержащим путь файла и причину (для висячей ссылки — её id)

### Requirement: Связи узлов выводятся из потоков
Сборка SHALL восстанавливать входящие и исходящие связи узлов по `sourceRef`/`targetRef` sequence flow до валидации и раскладки. Отсутствие элементов `incoming`/`outgoing` в источнике MUST NOT приводить к ошибкам валидации или к неверной раскладке.

#### Scenario: Потоки заданы только ссылками
- **WHEN** в `.bpmn` sequence flow заданы атрибутами `sourceRef`/`targetRef`, а у узлов нет `incoming`/`outgoing`
- **THEN** валидация не сообщает о несвязанных узлах, а диаграмма раскладывается с этими связями

### Requirement: Раскладка с горизонтальными пулами и дорожками
Сборка SHALL раскладывать диаграмму автоматически: пулы и дорожки — горизонтальные полосы с подписью слева, поток — слева направо, каждый узел — внутри полосы своей дорожки, message flow соединяют элементы разных пулов. Раскладка MUST быть детерминированной: один и тот же источник даёт одинаковые координаты. Если раскладка невозможна, сборка MUST завершаться ошибкой с путём файла и причиной, а не зависать или падать с трассой стека.

#### Scenario: Процесс с пулами и дорожками
- **WHEN** `.bpmn` содержит collaboration из двух пулов, у одного из них три дорожки, между пулами есть message flow
- **THEN** в SVG пулы и дорожки — горизонтальные полосы, узлы лежат в полосах своих дорожек, message flow соединяют пулы

#### Scenario: Ошибка раскладки
- **WHEN** движок раскладки не может разложить модель
- **THEN** сборка сообщает путь файла и причину, остальные диаграммы проекта не затронуты в отчёте об ошибке

### Requirement: Рендер в стандартной нотации без браузера
Сборка SHALL рендерить BPMN в SVG в стандартной нотации: маркеры событий (таймер, сообщение и др.), маркеры шлюзов, значки типов задач, пунктирные message flow. Рендер MUST выполняться локально, без браузера и без сетевых обращений. Метрики текста (перенос подписей, размеры) MUST вычисляться по вендорному шрифту независимо от режима системных шрифтов, чтобы повторный рендер одного источника давал байт-в-байт идентичный SVG. Идентификаторы внутри SVG MUST быть детерминированными. При `DIAGRAM_FORMAT=png` SVG растеризуется в PNG штатной растеризацией.

#### Scenario: Повторный рендер идентичен
- **WHEN** один и тот же `.bpmn` рендерится дважды, в том числе на разных машинах
- **THEN** SVG-выходы байт-в-байт совпадают

#### Scenario: Кириллица в подписях
- **WHEN** подписи задач, дорожек и пулов на русском
- **THEN** текст присутствует в SVG без искажений и переносится внутри фигур

#### Scenario: Сборка без сети
- **WHEN** сборка с `.bpmn` запускается в окружении без доступа в интернет
- **THEN** рендер завершается успешно

### Requirement: Семантическая валидация BPMN
Сборка SHALL валидировать каждую BPMN-модель фиксированным набором правил до раскладки. Набор MUST проверять как минимум: несвязанные узлы, отсутствие стартового или конечного события, узел вне дорожки или в нескольких дорожках (когда у процесса есть дорожки), sequence flow через границу пула, message flow внутри одного пула. Нарушение уровня error MUST прерывать рендер диаграммы с сообщением «путь файла, id элемента, правило, описание». Нарушение уровня warning MUST выводиться в лог без прерывания сборки.

#### Scenario: Узел без связей
- **WHEN** в процессе есть задача без входящих и исходящих потоков
- **THEN** рендер диаграммы прерывается с сообщением, содержащим путь файла, id задачи и имя правила

#### Scenario: Sequence flow между пулами
- **WHEN** sequence flow соединяет элементы разных пулов
- **THEN** валидация сообщает ошибку с id потока и подсказкой использовать message flow

#### Scenario: Узел вне дорожки
- **WHEN** у процесса есть дорожки, а узел не указан ни в одной из них
- **THEN** валидация сообщает ошибку с id узла

### Requirement: Проверка BPMN командой check
`c4builder check <file...>` SHALL принимать файлы `.bpmn` и выполнять для них те же разбор, валидацию, раскладку и рендер, что и сборка, без проекта и `.c4builder`. Код выхода MUST быть 0, только если все файлы прошли без ошибок; при ошибке — 1. Сообщения MUST содержать путь файла и, если известен, id элемента и имя правила. Предупреждения валидации MUST выводиться, но не влиять на код выхода.

#### Scenario: Ошибка валидации в check
- **WHEN** агент запускает `c4builder check process.bpmn` для модели с несвязанным узлом
- **THEN** команда печатает путь файла, id узла и правило и завершается с кодом 1

#### Scenario: Корректная модель
- **WHEN** `c4builder check process.bpmn` запускается для корректной модели
- **THEN** команда завершается с кодом 0

### Requirement: Зависимости BPMN опциональны и загружаются лениво
Пакеты BPMN-движка SHALL быть опциональными зависимостями. Они загружаются только при наличии в проекте (или в аргументах `check`) хотя бы одного `.bpmn`. При наличии `.bpmn` и отсутствии пакетов сборка MUST завершаться понятной ошибкой с указанием, как установить зависимости. После рендера ресурсы движка MUST освобождаться, чтобы процесс CLI завершался.

#### Scenario: Проект без BPMN
- **WHEN** в проекте нет `.bpmn`
- **THEN** пакеты BPMN-движка не загружаются, сборка и её выход не меняются

#### Scenario: .bpmn без установленных зависимостей
- **WHEN** в проекте есть `.bpmn`, а пакеты движка не установлены
- **THEN** сборка падает с понятным сообщением и подсказкой установки

### Requirement: Кэш BPMN-диаграмм учитывает версии движка
Чексумма кэша BPMN-диаграммы SHALL включать содержимое источника, формат вывода и версии пакетов раскладки, рендера и валидации. Смена любой из версий MUST приводить к перерисовке, а не к выдаче устаревшей картинки из кэша.

#### Scenario: Обновление пакета раскладки
- **WHEN** версия пакета раскладки изменилась, а источник — нет
- **THEN** при следующей сборке BPMN-диаграмма перерисовывается

## diagram-rendering

[Обзор](#C4-Builder)

# Spec Delta

## MODIFIED Requirements

### Requirement: Второй бэкенд рендера выбирается по расширению
Сборка SHALL поддерживать `.d2`- и `.bpmn`-диаграммы наравне с `.puml` и выбирать движок
рендера по расширению файла: `.puml` — PlantUML, `.d2` — D2, `.bpmn` — BPMN-движок (см.
capability `bpmn-diagrams`). Добавление движков MUST NOT менять поведение существующих
`.puml`-проектов; выходной файл диаграммы именуется по имени исходного файла. Формат рендера
всех движков — SVG; при `DIAGRAM_FORMAT=png` SVG растеризуется в PNG отдельной стадией (см.
требование о PNG-выводе).

#### Scenario: Смешанное дерево .puml и .d2
- **WHEN** в дереве проекта присутствуют и `.puml`, и `.d2` файлы
- **THEN** `.puml` рендерятся PlantUML, `.d2` рендерятся D2, при формате по умолчанию
  (svg) оба дают SVG рядом с прочими выходами, ссылки в markdown работают для обоих

#### Scenario: BPMN рядом с другими движками
- **WHEN** в дереве проекта присутствуют `.puml`, `.d2` и `.bpmn` файлы
- **THEN** каждый файл рендерится своим движком, `.bpmn` даёт SVG (или PNG при
  `DIAGRAM_FORMAT=png`) с именем по исходному файлу, ссылки в markdown работают для всех

#### Scenario: Проект только из .puml не затронут
- **WHEN** в проекте нет ни одного `.d2`- и `.bpmn`-файла
- **THEN** сборка и её выход идентичны прежнему поведению, а зависимости D2 и BPMN не
  загружаются

## project-template

[Обзор](#C4-Builder)

# Spec Delta

## MODIFIED Requirements

### Requirement: Демо-проект собирается офлайн
Проект, созданный `c4builder new`, SHALL собираться без доступа в интернет: рендер всех диаграмм шаблона (PlantUML, D2, BPMN) MUST выполняться локальными движками без сетевых обращений.

#### Scenario: Сборка нового проекта без сети
- **WHEN** проект создан из шаблона и `c4builder` запущен в окружении без доступа в интернет
- **THEN** сборка завершается успешно и все диаграммы шаблона отрендерены

## ADDED Requirements

### Requirement: Шаблон демонстрирует BPMN-процесс
Шаблон MUST содержать раздел с `.bpmn`-диаграммой без координат (без BPMN DI), с несколькими пулами, дорожками, событием-таймером и message flow, с кириллическими подписями, и md-страницей, поясняющей, что агент пишет только семантическую часть, а раскладку делает сборка.

#### Scenario: BPMN-пример в новом проекте
- **WHEN** собирается новый проект из шаблона
- **THEN** BPMN-диаграмма раздела отрендерена с горизонтальными пулами и дорожками, а `c4builder check` для её файла завершается с кодом 0

## regression-testing

[Обзор](#C4-Builder)

# Spec Delta

## ADDED Requirements

### Requirement: Golden-тест покрывает BPMN-рендер
Golden-fixture SHALL включать `.bpmn`-диаграмму с collaboration из нескольких пулов, дорожками, промежуточным или граничным событием-таймером, message flow и кириллическими подписями. Golden-тест MUST сравнивать её SVG-выход (вариант `default`) и PNG-выход (вариант `embed-png`) с эталонами наравне с PlantUML и D2. Детерминизм обеспечивается вендорным шрифтом для метрик текста и точным пином версий пакетов раскладки и рендера.

#### Scenario: BPMN-диаграмма в fixture совпадает с эталоном
- **WHEN** golden-тест собирает fixture, содержащий `.bpmn`
- **THEN** её SVG (после нормализации) совпадает с закоммиченным эталоном

#### Scenario: Повторный прогон BPMN идентичен
- **WHEN** сборка fixture с `.bpmn` выполняется дважды
- **THEN** SVG-выход BPMN-диаграммы байт-в-байт совпадает между прогонами

#### Scenario: Обновление пакета раскладки ловится тестом
- **WHEN** версия пакета раскладки или рендера меняется и меняет координаты
- **THEN** golden-тест падает до явного переснятия эталона

## 2026-10-03-pr8-review-fixes

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-17 · **Tasks:** <progress value="23" max="23"></progress> 23/23 (100%) · **Updated:** 2026-10-06

[tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-pr8-review-fixes/tasks/tasks) · [README](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-pr8-review-fixes/README/README)

## Why

Max-ревью PR #8 (`refactor/phoenix` → `master`, полный TS-порт) нашло 15 верифицированных дефектов: 10 finder-углов → адверсариальная верификация каждого кандидата отдельным агентом (14 CONFIRMED, 1 PLAUSIBLE, часть — рантайм-проверками), финальный sweep. Среди них три регрессии против master, ломающие рабочие конфиги пользователей `0.2.x`, уничтожение бэкапа при упавшей сборке, zip-slip и баг, законсервированный в golden-эталоне. Чиним до мержа PR #8.

## What Changes

- Исправляются дефекты в `src/config/schema.ts`, `src/cli/dispatch.ts`, `src/cli/wizard/collect.ts`, `src/core/build.ts`, `src/core/render/{jre,diagrams,d2renderer}.ts`, `src/core/scan/tree.ts`, `src/core/compose/markdown.ts` — полный список с механикой и сценариями в `tasks.md` (он самодостаточен: контекст ревью, file:line, подход к фиксу, как проверить).
- **Golden-эталоны будут перегенерированы**: фикс путей картинок в complete-md (задача 4.1) меняет байты `test/golden/*` — это ожидаемо, эталон сейчас консервирует баг (`test/golden/default/tree/golden-fixture.md:54` содержит `![diagram](system.svg)` при файле в подпапке).
- Поведение выравнивается с master там, где порт внёс регрессии; новых фич нет.

## Capabilities

### New Capabilities
<!-- Нет -->

### Modified Capabilities
<!-- Без spec-дельт: все фиксы возвращают подразумеваемое требованиями поведение
     (config-validation: терпимость к легаси-значениям; diagram-rendering: ленивый
     резолв JRE был зафиксирован в jre-resolution как «ленивый»; output-formats:
     корректные ссылки). Если при реализации выяснится, что какое-то требование
     реально меняется — добавить дельту тогда. -->

## Impact

- **Файлы**: только `src/**` + перегенерация `test/golden/*` (+ возможно `test/*.mjs` для новых регрессионных кейсов).
- **Пользователи**: легаси-конфиги (`docsifyTemplate: false`, `null` в массивах, битые ключи) снова работают/чинятся визардом вместо exit 1.
- **CI**: зелёный до и после; golden-обновление — отдельным коммитом с объяснением.
- PR #8 не мержить до закрытия минимум секции 1–5 tasks.md (секция 6 — опциональная).

## tasks

[Обзор](#C4-Builder)

<!-- САМОДОСТАТОЧНЫЙ КОНТЕКСТ (для работы после сброса контекста):
Ветка refactor/phoenix, PR #8 (draft снят, НЕ мержить до фиксов). Все находки —
из max-ревью 2026-07-17: 10 finder-углов, каждый кандидат верифицирован отдельным
агентом (вердикты в тексте задач), sweep-проход. Номера строк — на момент ревью
(коммит be99acd), при дрейфе искать по описанию механики.
Сборка: npm run build (tsc → dist/). Тесты: npm test; golden: npm run test:golden,
перегенерация эталонов: npm run test:golden:update (нужна после фиксов секции 4!).
Правило репо: коммиты БЕЗ номера задачи (публичный ai-sandbox), стиль — как
`rc-publish: ...` в git log. После каждой секции — сборка + тесты. -->

## 1. Регрессии конфига (schema.ts / dispatch.ts / collect.ts)

- [x] 1.1 `schema.ts:32,33` (CONFIRMED, рантайм): `z.coerce.string()` превращает boolean в `'false'/'true'` — `docsifyTemplate:false` → `require('<cwd>/false')` → MODULE_NOT_FOUND; `webPort:false` → `app.listen('false')` слушает unix-сокет. Фикс: в `nullish`-препроцессе (или отдельным preprocess для строковых полей) трактовать `false` как «не задано» (→ дефолт), либо запретить boolean понятной ошибкой; для `webPort` дополнительно валидировать что строка — число 1..65535 (закроет и опечатку «30OO», которая сейчас тоже даёт unix-сокет + битый URL «localhost:30OO»; parseInt-флаг `-p 30OO` тихо биндит порт 30 — заодно `parseInt` → строгая проверка). Проверка: unit на safeParse с false/числом + ручной `--site`.
- [x] 1.2 `schema.ts:48` (CONFIRMED, рантайм): `null` внутри `excludeSidebarFolderByPath` валит строгую валидацию с exit 1 (master молча игнорировал; runtime-guard в `markdown.ts:330` теперь мёртв — заодно упростить до `?.some(startsWith)`). Фикс: препроцесс массива — отфильтровать не-строки (можно с warn), z.array(z.string()) после фильтра. Проверка: unit safeParse `['a', null]` → ok.
- [x] 1.3 `dispatch.ts:215` + `collect.ts:96-230` (CONFIRMED): ловушка salvage — визард не переспрашивает вложенные битые ключи (блоки гейтятся по валидным generate*-флагам; diagramsOnTop вообще не входит в условие своего блока), `conf.set('hasRun',true)` (dispatch.ts:207) пишется ДО строгого `parseConfig` (214) → exit 1 навсегда (следующие запуски падают на 201 до визарда). Фикс (минимальный, без перестройки визарда): на salvage-пути перед вызовом визарда физически перезаписать битые ключи salvaged-значениями (issues уже известны — `conf.set(key, salvaged[key])` по списку), и/или писать hasRun только ПОСЛЕ успешного parseConfig. Проверка: e2e-сценарий из ревью — `.c4builder` с `"includeNavigation":"yes"` без hasRun → запуск → повторный запуск должен работать.
- [x] 1.4 `dispatch.ts:51-52` (CONFIRMED): `k in raw` считает `"rootFolder": null` заданным (nullish уже превратил в дефолт 'src') → визард молча пропускает промпт, вопреки комментарию схемы «null = не задан». Фикс: фильтровать ключи со значением null так же, как отсутствующие (`k in raw && raw[k] !== null`). Проверка: конфиг с rootFolder:null → визард спрашивает папку.

## 2. Lifecycle сборки (build.ts / diagrams.ts)

- [x] 2.1 `build.ts:97-104` (CONFIRMED): finally безусловно сносит dist_bk — при упавшей сборке уничтожается единственная полная копия прошлого билда (master удалял только после всех фаз). Фикс: удалять dist_bk только при успехе (флаг ok после фаз; в finally — только teardownD2), при падении оставить dist_bk и написать в лог, что бэкап сохранён. Проверка: искусственно уронить рендер (битый .puml) → dist_bk на месте.
- [x] 2.2 `diagrams.ts:396-400` (CONFIRMED, waste): `throw failed.reason` раньше `cacheConf.set('checksums', newChecksums)` — чексуммы успешно отрендеренных в упавшем прогоне теряются. Фикс: set до throw (или в finally генерации), сохранять чексуммы только реально отрендеренных/восстановленных. Вместе с 2.1 повторный прогон после сбоя чинит только упавшую диаграмму.

## 3. JRE (jre.ts / diagrams.ts)

- [x] 3.1 `diagrams.ts:269-273` (CONFIRMED, регрессия): needsJava по наличию PlantUML-диаграмм → resolveJava (вплоть до скачивания ~50 МБ) даже когда всё восстановится из кеша; офлайн-машина без java с собранным проектом теперь падает. Фикс: ленивый резолв — резолвить при ПЕРВОЙ диаграмме, реально требующей рендера (промис-синглтон внутри generateImages после решения «кеш не сработал»). Спека jre-resolution фиксирует «ленивый резолв» — фикс возвращает соответствие. Проверка: собранный проект + PATH без java → повторная сборка проходит.
- [x] 3.2 `jre.ts:150-161,387-388` (CONFIRMED): cachedJava не проверяет запускаемость (detectSystemJava гоняет javaMajor, кеш — нет) → полубитый кеш валит сборку без фолбэка. Фикс: прогонять javaMajor и на кешированном бинаре; при провале — сносить каталог кеша и идти в download.
- [x] 3.3 `jre.ts:326,345-346` (CONFIRMED): установка в общий кеш rmSync→renameSync без межпроцессной блокировки: дубль-скачивание на холодном кеше, окно ENOENT, ENOTEMPTY при гонке. Фикс: если dir уже валиден к моменту установки — просто выбросить свой stage (перепроверка после скачивания); rename без предварительного rm (rename поверх существующего → catch EEXIST/ENOTEMPTY = «другой процесс успел» → ок); опционально lockfile.
- [x] 3.4 `jre.ts:281` (CONFIRMED, security): zip-slip в extractZip — `path.join(destDir, entry.fileName)` без containment-проверки (tar-ветка защищена node-tar≥6). Фикс: `const dest = path.resolve(destDir, entry.fileName); if (!dest.startsWith(path.resolve(destDir) + path.sep)) throw` (+ пропуск симлинков). Проверка: unit с фейковой записью `../evil`.

## 4. Compose (markdown.ts / tree.ts) — МЕНЯЕТ GOLDEN

- [x] 4.1 `markdown.ts:122` (CONFIRMED, унаследовано из master, зафиксировано в golden!): в complete-md `![diagram](diagramUrl)` без префикса папки (linkHref на 106-109 префикс имеет) → битые картинки для диаграмм вне корня. Фикс: в complete-варианте не-remote ветки использовать префиксованный путь и для image (тот же расчёт, что linkHref). После фикса: `npm run test:golden:update` + глазами проверить `test/golden/*/tree/*-fixture.md` — пути должны стать `<папка>/<имя>.svg`.
- [x] 4.2 `markdown.ts:43-48,167` (CONFIRMED): при пользовательском h1 + diagramsOnTop нессылочные диаграммы попадают ВЫШЕ h1 (injectAfterFirstH1 заглатывает блок диаграмм вместе с заголовком). Фикс: структурная сборка — выделять пользовательский h1 из texts[0] ДО compileDocument (или передавать ownH1 внутрь и вставлять diagrams после заголовка), порядок всегда h1 → chrome → (диаграммы|текст по DIAGRAMS_ON_TOP). Добавить тест-кейс: md с `# Title` + нессылочная диаграмма + diagramsOnTop (golden не покрывает — ни один template/src/*.md не начинается с '# ').
- [x] 4.3 `tree.ts:84-91` + guard :60 (CONFIRMED): DIST_FOLDER попадает в descendants до раннего return рекурсии → битая ссылка в nav-меню + мусорный docs/docs при rootFolder='.'. Фикс: проверять `path.join(dir, file) === options.DIST_FOLDER` ДО push в descendants/makeDirectory (guard внутри цикла, а не только в рекурсии).
- [x] 4.4 `markdown.ts:372,387` (CONFIRMED, рантайм): require ESM-шаблона возвращает namespace → «docsifyTemplate is not a function». Фикс: `const m = require(...); docsifyTemplate = typeof m === 'function' ? m : (typeof m?.default === 'function' ? m.default : throw понятная ошибка)`.

## 5. Рендер-инфраструктура (d2renderer.ts / diagrams.ts)

- [x] 5.1 `d2renderer.ts:64-68` (CONFIRMED): teardownD2 в finally build() повторно await-ит упавший inst.ready и затирает исходную ошибку сборки. Фикс: `try { await inst.ready } catch { /* уже отражено ошибкой рендера */ }` + terminate в finally; teardown идемпотентен.
- [x] 5.2 `diagrams.ts:107-128` (CONFIRMED): второй httpGet без таймаутов и редиректов (двойник jre.ts:175-204 имеет оба) — embed-сборка с онлайн-рендером виснет навсегда/падает на 302. Фикс: общий хелпер (util/http.ts): jre-версия (redirect-follow + CONNECT/IDLE таймауты) + обёртка «собрать тело в Buffer»; заодно вычистить стену тривиальных легаси-комментариев (7 шт., нарушают правило «комментарии только важные»).

## 6. Ниже капа — опционально, по желанию (НЕ блокирует мерж PR #8)

- [x] 6.1 `dispatch.ts:151` (PLAUSIBLE): Configstore для .c4builder.cache — RMW-гонка конкурентных запусков (watch + ручная сборка). Следствие — потеря чексумм/лишний перерендер, не порча. Вариант: пропускать запись кеша в watch-режиме или file-lock. → Сделано file-lock'ом на всю сборку (`src/util/lock.ts` + обвязка в dispatch): чинит заодно и гонку dist/dist_bk; протухший лок (мёртвый pid / старше часа) снимается сам; watch пропускает ребилд с коротким сообщением; юнит-тесты `test/lock.test.mjs` + ручной E2E.
- [x] 6.2 `ci.yml:83-97` (CONFIRMED): grep констант TEMURIN_FEATURE/JRE_CACHE_SCHEMA из jre.ts без гейта на пустой результат (echo глотает код grep даже под bash -e) + хардкод пути `~/.cache/c4builder/jre` (XDG_CACHE_HOME разъедется). Фикс: `[ -n "$v" ] || exit 1` после извлечения; лучше — `c4builder jre info --json` (CLI-подкоманда, отдающая путь и материал ключа). → Сделана подкоманда `c4builder jre info` (всегда JSON: feature/schema/cacheDir); CI берёт параметры из неё через jq с гейтом на пустые значения, путь кеша — из cacheDir.
- [x] 6.3 `d2renderer.ts:190` + `tree.ts:189` (механика подтверждена чтением): чексуммы включают АБСОЛЮТНЫЕ пути импортов (.d2 и .iuml) — кеш непереносим между машинами/чекаутами. Фикс: класть в материал путь относительно ROOT_FOLDER. → Сделано: путь относительно cwd, posix-разделители (переносимо и между ОС); существующие кеши инвалидируются один раз (штатный перерендер).
- [x] 6.4 `d2renderer.ts:98` (подтверждено чтением): D2-файлы читаются hardcoded utf-8, опция CHARSET игнорируется (PlantUML честно получает -charset). Фикс: читать с CHARSET или задокументировать «D2 = только UTF-8». → Решение: D2 = только UTF-8 (язык определён поверх UTF-8; iconv-зависимость не оправдана), задокументировано у места чтения.
- [x] 6.5 `d2renderer.ts:133-142` (подтверждено чтением): commonAncestor на пустом наборе файлов (вход не прочитался — гонка в watch) → `Math.min()`=Infinity → сырой TypeError вместо понятной ошибки. Фикс: guard на пустой files с внятным сообщением. → Сделано в buildCompileRequest.
- [x] 6.6 Перф-темы (CONFIRMED, по желанию): JVM-спавн на каждую диаграмму (батчинг осложнён выбором -pipe ради контроля имён — см. коммент diagrams.ts:130-133); синхронный resvg.render → renderAsync; foldIncludes без мемоизации (N×M чтений .iuml — у D2 filesMemo уже есть); httpGet embed-ветка мимо diagramBase64Cache; teardownD2/пересоздание воркера на каждый watch-ребилд; statSync×2 в tree.ts (withFileTypes); golden на обеих ногах CI-матрицы; docker-publish без buildx-кеша; base64-кеш не чистится в finally (память watch). → Сделано всё, КРОМЕ JVM-батчинга (осознанно: -pipe нужен для контроля имён выхода, пул уже параллелит; фиксируем как принятое решение): renderAsync; кеш чтения include (clearIncludeCache); embed-httpGet через diagramBase64Cache; teardownD2 перенесён в dispatch (в watch воркер живёт между ребилдами, кеш графа сбрасывает clearD2FileCache); withFileTypes (симлинкам — statSync); golden на одной ноге матрицы (node 24), вторая — `npm run test:unit`; buildx gha-кеш в docker-publish; все пофайловые кеши чистятся и в finally build().
- [x] 6.7 Cleanup-темы (перечислены в ревью, без вердиктов): дубли relative-link блоков ×3 и якорей ×2 в markdown.ts; splice(1) сайдбара vs replace(ROOT_FOLDER) (ломается на многосегментном rootFolder); тернарники ×9 и find→includes ×11 в collect.ts; generateTemplate=40 строк вместо fsextra.copy; IO-обёртки utils.ts (мёртвый параметр type, глотание EACCES в makeDirectory); мёртвые экспорты tree.ts (DiagramExt и др., ложный коммент «для тестов» у diagramRefRegex); 24×nullish(...) в schema.ts; generateWebMD дублирует скелет generateMD (trimStart уже разъехался); движковые if/else мимо реестра DIAGRAM_ENGINES (~9 веток в 4 файлах); тесты импортируют dist/ глубокими путями (уронит будущий build-split); утечка temp-папок в golden.test.mjs beforeAll при падении посреди цикла. → Сделано: relativeMdLink/mdAnchor/compilePage в markdown.ts (golden байт-в-байт); сайдбар через path.relative (заодно чинит ссылки при rootFolder='.'); checkedKey+includes в collect.ts; generateTemplate = fsextra.copy; utils.ts на fs.promises (mkdir -p, EACCES пробрасывается, Buffer-возврат readFile); DiagramExt удалён, diagramRefRegex деэкспортирован; 24×nullish закрыт ещё секцией 1; реестр расширен способностью remoteRender (build/compose ветвятся по ней; render-ветки PlantUML/D2 остаются осознанно — пути реально разные); тесты ходят в dist/ через единый test/dist.mjs; фикстуры golden регистрируются до сборки + anyFailed при падении хука.

## README

[Обзор](#C4-Builder)

# pr8-review-fixes

Починка находок max-ревью PR #8: 15 верифицированных дефектов TS-порта (регрессии конфига, lifecycle сборки, JRE, compose)

## 2026-10-03-plugin-system

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-08-16 · **Tasks:** <progress value="27" max="27"></progress> 27/27 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/specs/specs)

## Why

Арх-репы (arch и соседний арх-репо) держат рядом с C4/ADR живой OpenSpec-store (18 активных
change'ов, растущий архив) и потребляют 15 OpenAPI-контрактов из репозитория контрактов, но на
docsify-сайте ничего из этого не видно: читатель ходит по сырым папкам GitLab, а design.md с
```plantuml через docsify-plantuml утекал бы в www.plantuml.com прямо из браузера. Готовые
вьюверы OpenSpec (spek, openspec-viewer, openspecui) — отдельные SPA/серверы, с docsify и
c4builder не стыкуются. Нужен штатный способ расширять сайт внешними источниками без правки
ядра под каждый — и первые два расширения: OpenSpec и OpenAPI.

## What Changes

- **Система плагинов ядра.** Новый ключ `.c4builder` `plugins` (список: `"имя"` или
  `["имя", {опции}]`); плагин — ESM-модуль (встроенный по имени, локальный путь или
  npm-пакет) с хуками `afterScan` (виртуальные страницы в дереве сборки) и `afterBuild`
  (ассеты/проверки). Виртуальные страницы проходят штатный compose: sidebar, поиск,
  complete.md, generateMD; их диаграммы рендерятся локальным движком. Плагин может объявить
  дополнительные пути для watch-режима и zod-схему опций (строгая: неизвестный ключ — ошибка);
  ошибки валидации — до старта сборки. Скрипты/стили плагинов дописываются в готовый
  `index.html` пост-обработкой, независимо от пользовательского `docsifyTemplate`.
- **Резолвер источников** для плагинов: `dir` (локальная папка) или `archive` (tar.gz/zip по
  HTTP с опциональным токеном из `${ENV}`) → локальный кэш-каталог; плагин всегда работает с
  папкой. Без новых зависимостей (`tar`, `yauzl`, `util/http` уже есть).
- **Встроенный плагин `openspec`.** Локальный store (`dir`, по умолчанию `openspec`) →
  раздел сайта (`mount`, по умолчанию `OpenSpec`): сводка (счётчики, прогресс задач),
  страницы активных change'ов (proposal · design · дельты спек · tasks), спеки по областям,
  архив. ```plantuml-блоки артефактов вырезаются в диаграммы и рендерятся локально.
- **Встроенный плагин `openapi`.** Источник (`dir`/`archive`) + `glob` → раздел (`mount`, по
  умолчанию `API`) со страницей на спеку: swagger-ui на вендорном бандле (JS уже в
  `vendor/docsify`, CSS вендорится — без unpkg), спека копируется в dist статикой; при
  наличии плагина `executeScript` включается автоматически.
- Старые версии c4builder ключ `plugins` молча игнорируют (схема нестрогая) — откат образа
  не ломает сборку арх-реп.

## Capabilities

### New Capabilities
- `plugin-system`: загрузка и валидация плагинов из `.c4builder`, хуки `afterScan`/`afterBuild`,
  виртуальные страницы в дереве, watch-пути, инъекция ассетов в `index.html`, резолвер
  источников `dir`/`archive`.
- `openspec-plugin`: генерация раздела сайта из локального OpenSpec-store (сводка, changes,
  specs, archive), локальный рендер диаграмм артефактов.
- `openapi-plugin`: генерация раздела swagger-ui из набора OpenAPI-спек (локальных или из
  архива репозитория), офлайн-ассеты.

### Modified Capabilities
- (нет — `config-validation` уже требует единую zod-схему; новый ключ и строгие схемы опций
  плагинов описываются в `plugin-system`)

## Impact

- `src/config/schema.ts`, `src/config/options.ts` — ключ `plugins`.
- `src/core/build.ts`, `src/cli/dispatch.ts` — загрузка плагинов до сборки, вызов хуков,
  watch-пути.
- `src/core/compose/markdown.ts` — пост-инъекция ассетов плагинов в `index.html`.
- Новые модули: `src/core/plugins/` (типы, загрузчик, резолвер источников),
  `src/plugins/openspec/`, `src/plugins/openapi/`.
- `vendor/docsify/` — `swagger-ui.css` (вендор, версия в паре с `swagger-ui-bundle.js`).
- Тесты: vitest на загрузчик/схемы, на генерацию страниц openspec и openapi по мини-фикстурам;
  golden-эталоны не меняются (плагины по умолчанию выключены).
- README: раздел «Plugins» (конфиг, встроенные плагины, контракт стороннего плагина).
- Потребители: арх-репы — одна правка `.c4builder` (`plugins`), CI и `docsify-template.js`
  без изменений; образ `:rc` подхватывает версию.
- Новых npm-зависимостей нет.

## design

[Обзор](#C4-Builder)

## Context

См. proposal.md — Why. Опорные факты ядра, на которые ложится дизайн:

- Пайплайн `build()`: `generateTree` (scan) → `generateImages` (render) → `generateMD` /
  `generateWebMD` / `generateCompleteMD` (compose). Дерево — плоский массив `TreeItem` в
  DFS-порядке; sidebar и навигация строятся из порядка и `level`.
- `TreeItem.mdFiles` хранит **содержимое** страниц (`string | Buffer`), не пути; compose
  диск для markdown не трогает — виртуальные элементы проходят без специальных веток.
  Ссылка `![x](name.puml)` в тексте заменяется inline на отрендеренную диаграмму из
  `item.diagrams`; неупомянутые диаграммы дописываются в начало/конец страницы.
- Рендер PlantUML: `foldIncludes` разворачивает только локальные `!include` относительно
  `item.dir`; stdlib-инклюды (`<C4/...>`) уходят в JAR как есть — виртуальный `dir` им не
  мешает.
- Watch (`dispatch.ts`) слушает только `ROOT_FOLDER`; `docsifyTemplate` — пользовательская
  функция, возвращающая **весь** HTML (оба арх-репо держат свои копии).
- В deps уже есть `zod` 4, `tar` 7, `yauzl` (с zip-slip-guard в `render/jre.ts`),
  `util/http.ts` (httpGet), `vendor/docsify/swagger-ui-bundle.js`. Нет: glob-библиотеки,
  yaml-парсера. Engines `>=20.19` — `fs.glob`/`path.matchesGlob` недоступны.
- Публичный репозиторий: в дефолтах и тестах нет внутренних хостов; корпсреда без
  интернета — рендер только локальный.

## Goals / Non-Goals

**Goals:**
- Минимальный, но достаточный контракт плагина: два хука, декларации (опции-схема,
  ассеты, watch-пути, требования), общий резолвер источников.
- Виртуальные страницы — «граждане первого сорта» дерева: никакой параллельной ветки
  compose.
- Ноль новых зависимостей; golden-эталоны без изменений (плагины по умолчанию выключены).
- Арх-репы подключаются одной правкой `.c4builder`.

**Non-Goals:**
- Плагины-движки диаграмм (mermaid/structurizr/kroki): `DIAGRAM_ENGINES` остаётся статичным
  реестром — отдельный change при потребности.
- Удалённый OpenSpec-store, резолв store по реестру машины (`store: <id>`), фильтрация
  change'ов по репозиторию — не сейчас; резолвер `archive` закладывается общим слоем, но
  openspec-плагин в этом change работает только с `dir`.
- Публикация плагинов отдельными npm-пакетами: встроенные живут в пакете c4builder;
  внешние загружаются тем же загрузчиком, но не поставляются.
- Клиентские docsify-плагины (tabs, copy-code…) как встроенные — не в этом change; путь для
  них (`assets`) появляется, наполнение — позже.

## Decisions

### D1. Контракт плагина — плоский объект с декларациями и двумя хуками

```ts
export default definePlugin<Opts>({
  name: 'openapi',
  options: z.object({...}).strict(),                 // опционально; для встроенных — обязательно
  watchPaths: (opts) => string[],                     // опционально
  assets: { scripts: string[]; styles: string[] },    // абсолютные пути файлов плагина; опционально
  requires: { executeScript?: true },                 // опционально
  afterScan?: (ctx: ScanCtx) => Promise<void>,        // ctx.tree, ctx.options, ctx.addPage(), ctx.source()
  afterBuild?: (ctx: BuildCtx) => Promise<void>,      // ctx.distFolder, ctx.options
});
```
`definePlugin` — identity-функция ради типизации. Почему не событийная шина/tapable: два
хука покрывают все известные кейсы (страницы, ассеты, проверки), а шина — абстракция без
второго потребителя. Почему `afterScan`, а не `beforeScan` с генерацией файлов в `src/`:
запись в исходники ломает watch (петля) и пачкает git; виртуальные элементы бесплатны.

### D2. `ctx.addPage()` вместо ручной сборки TreeItem

Плагин задаёт путь сегментами (`['OpenSpec','Changes','dig-1']`), markdown и диаграммы;
хелпер ядра сам считает `dir` (= `ROOT_FOLDER/сегменты`, виртуальный), `level`, `parent`,
`descendants` родителя и вставляет элемент в конец поддерева родителя (DFS сохраняется —
sidebar/навигация не требуют правок). Отсутствующие промежуточные сегменты создаются
пустыми страницами-оглавлениями (список детей). Пустой `mdFiles` у промежуточного узла
даёт авто-заголовок, как у папки без README. Альтернатива «плагин сам конструирует
TreeItem» отвергнута: инварианты дерева (порядок, descendants) — внутреннее знание ядра.

Дублирование пути (плагин монтируется поверх реальной папки `src/OpenSpec`) — ошибка
загрузки с понятным текстом, а не тихое слияние.

### D3. Загрузка и валидация — в `dispatch` до `build()`, fail-fast

`loadPlugins(config.plugins, cwd)`: резолв идентификатора — встроенный (`src/plugins/index.ts`,
карта имя → модуль) → путь (`./`, `../`, `/`, `pathToFileURL` + `import()`) → npm
(`createRequire(cwd)` + `import()`); ошибка резолва называет идентификатор и причину.
Опции: обход строк с подстановкой `${NAME}` из `process.env` (незаданная → `''`) → `schema.safeParse` →
ошибка `plugins[i] <name>: <path> — <issue>`. Загруженные плагины передаются в `build()`
третьим аргументом (по аналогии с `cacheConf`), не через `BuildOptions` — опции остаются
сериализуемым снимком конфига. Плагин с `requires.executeScript` включает
`options.EXECUTE_SCRIPT` с одной строкой в лог. Почему zod `.strict()` для встроенных при
нестрогой верхней схеме: поверхность опций мала, опечатка `globs` иначе даёт пустой раздел
без ошибки; верхний уровень не трогаем ради совместимости старых конфигов.

### D4. Ассеты — пост-инъекция в готовый `index.html`

После `generateWebMD` ядро копирует `assets` всех плагинов в `dist/vendor/plugins/<name>/` и
дописывает `<link rel="stylesheet">` перед `</head>` и `<script src>` перед `</body>`
(регистронезависимо; при отсутствии тегов — в конец файла). Альтернатива — прокинуть в
`docsifyTemplate` новый аргумент — отвергнута: оба арх-репо и любой чужой шаблон пришлось
бы править, а хардкод тегов в шаблоне arch и так гейтится `executeScript`; пост-инъекция
работает с любым шаблоном. Скрипт swagger-ui не в `assets` — он уже вендорен и подключается
существующей веткой `executeScript`; в `assets` только `swagger-ui.css` (той же версии, что
bundle; версия зафиксирована в имени/комментарии рядом с `vendor/docsify`).

### D5. Watch — дополнительные пути через тот же `node-watch`

`dispatch` собирает `watchPaths` всех плагинов, отбрасывает несуществующие (с
предупреждением) и добавляет их к вызову `watch` (node-watch принимает массив путей).
Debounce/защита от параллельной сборки — существующие.

### D6. Резолвер источников: `dir` | `archive`, кэш на процесс

`ctx.source({dir} | {archive, subdir?, headers?})` → абсолютный путь. `archive`: `httpGet` →
`os.tmpdir()/c4builder-src-<sha1(url)>/` → распаковка (`tar` для `.tar.gz`/`.tgz`,
`extractZip` из `jre.ts`, вынесенный в `util/archive.ts`, для `.zip`; zip-slip-guard общий)
→ если в корне ровно один каталог (GitLab/GitHub archive кладут `<repo>-<sha>/`), он
отбрасывается → затем `subdir`. `Map<url, path>` на модуль: в watch-режиме повторные сборки
не качают. `headers` — карта заголовков (пустые значения после подстановки `${ENV}`
отбрасываются): так один конфиг покрывает `PRIVATE-TOKEN: ${GITLAB_TOKEN}` локально и
`JOB-TOKEN: ${CI_JOB_TOKEN}` в CI, а публичные/internal-репо не требуют ничего. Почему не
`git clone`: нужен git-бинарь и ssh/https-креды в образе; archive API GitLab отдаёт tar.gz с
фильтром `path=` одним HTTP-запросом (проверено на репозитории контрактов — без токена).

### D7. Glob и yaml — свои мини-реализации, без зависимостей

`glob → RegExp` (`**`, `*`, `{a,b}`, экранирование остального) + рекурсивный обход — ~20
строк; покрывает `*/openapi.yaml` и дефолт `**/openapi.{yaml,yml,json}`. Метаданные
change'а (`schema:`, `created:` в `.openspec.yaml`) — построчный regex; парсер yaml для двух
скаляров не нужен. Если появится потребность в `info.title` спек — тогда yaml-парсер
отдельным решением.

### D8. Плагин openspec — состав страниц и диаграммы

- Сканер: `changes/*` (кроме `archive`) — change; артефакты — `*.md` корня, дельты —
  `specs/**/spec.md`; `specs/**/spec.md` store — спеки, промежуточные папки — подразделы.
  Прогресс: regex чекбоксов по всему `tasks.md`; «последнее изменение» — max mtime файлов
  change'а. Раскладка change'а — гибрид (решение 2026-08-16 после просмотра arch):
  страница change'а = шапка (метаданные, прогресс, ссылки на подстраницы) + первый
  артефакт из опции `artifacts` (дефолт `proposal, design, tasks` — «зачем» видно без
  клика); остальные артефакты — подстраницы в порядке опции, не перечисленные — по алфавиту;
  дельты — подраздел `specs` со страницей на capability (зеркалит `Specs/`). Плоская
  «всё на одной странице» отвергнута: нет отдельного URL на tasks/design, длинный design
  тянет всю страницу; «всё подстраницами» — лишний клик до сути change'а. Сводка
  сортируется по mtime desc, sidebar — по имени.
- Диаграммы: fence ```plantuml/```d2 → `Diagram { dir: '<артефакт>-<n>.<ext>', engine, content }`
  (PlantUML оборачивается в `@startuml/@enduml`, если их нет), в тексте — `![…](<имя>)`;
  compose заменяет ссылку inline (существующая логика), рендер — общий локальный. Клиентский
  docsify-plantuml не срабатывает: fence в выводе уже отсутствует.
- Относительные ссылки внутри change'а на файлы вне `*.md` (картинки) — копируются в
  выходной каталог той страницы, где на них ссылаются; ссылки на артефакты того же change'а
  переписываются на страницы сайта (якорь `#x` → `?id=x` docsify).
- Не шеллим `openspec` CLI: сборка не должна зависеть от установленного CLI и его версии.

### D9. Плагин openapi — статика рядом со страницей

Найденные по `glob` файлы копируются в `dist/<mount>/_specs/<относительный путь>` (вся
относительная структура источника сохраняется → относительные `$ref` работают). Страница
`<mount>/<name>` — минимальный md с `<div id>` и `<script>SwaggerUIBundle({url: '<относит.
путь>', dom_id, …})</script>` (та же схема, что в шаблоне `--new`), без CDN. Имя страницы —
родительская папка (в корне источника — имя файла); коллизии имён — ошибка.

## Risks / Trade-offs

- [Виртуальные `dir` вне диска] → `generateImages` использует `item.dir` только для
  локальных инклюдов и путей вывода; при апгрейде ядра любой новый `fs`-доступ по `item.dir`
  ловится юнит-тестом «виртуальный элемент собирается без каталога на диске».
- [Пост-инъекция в чужой HTML] → детерминированные точки вставки и тест на шаблон без
  `</head>`; хуже сломать невозможно — при промахе теги в конце файла всё равно исполняются.
- [Кэш архива в `os.tmpdir()`] → ключ по sha1(url), очистка не нужна (tmp), в CI раннер
  одноразовый; параллельные сборки одного URL пишут в один каталог — распаковка в
  `<dir>.tmp` + rename.
- [Секреты в `${ENV}`] → значения заголовков не логируются; в вывод сборки не попадают.
- [swagger-ui.css вендорится] → +~150 КБ в пакете; whitelist `files` уже включает `vendor/`.
- [Рост архива OpenSpec → длинный sidebar] → sidebar-collapse на стороне arch уже стоит;
  группировка по годам — когда понадобится (в спеке не фиксируем).
- [`.strict()` у встроенных плагинов ломает конфиг при переименовании опции] → переименования
  через deprecated-алиас с предупреждением, как с легаси-ключами конфига.

## Migration Plan

1. Релиз `rc` c4builder → образ `:rc` (арх-репы на нём).
2. В арх-репо: `plugins` в `.c4builder` (openspec — `dir: openspec`; openapi —
   `archive` на репозиторий контрактов, `glob: */openapi.yaml`). Заодно убрать легаси-ключи
   `plantumlVersion`/`generatePDF*`.
3. Проверка через MR-preview Pages; после — обычный релиз `v*`.
4. Откат: вернуть образ на `:latest` — ключ `plugins` игнорируется, сайт собирается без
   разделов.

## Open Questions

- Нужен ли на сводке OpenSpec блок ссылок ADR ↔ change (обратный индекс по «Основание:
  ADR-NNN»)? Не влияет на API и разбиение задач — можно добавить отдельным change'ом.

## tasks

[Обзор](#C4-Builder)

## 1. Конфиг и контракт плагина

- [x] 1.1 `config/schema.ts`: ключ `plugins` — массив `string | [string, Record<string, unknown>]`, дефолт `[]`; ошибка формы с путём ключа; `BuildOptions`/`getOptions` пробрасывают сырой список
- [x] 1.2 `core/plugins/types.ts`: `definePlugin`, типы `Plugin`, `ScanCtx`, `BuildCtx`, `PageSpec` (сегменты пути, markdown, диаграммы), `SourceSpec` (`dir` | `archive`+`subdir`+`headers`)
- [x] 1.3 `core/plugins/load.ts`: резолв идентификатора (встроенный → путь от cwd → npm через `createRequire`), `import()`, подстановка `${ENV}` в опциях, `safeParse` схемы с сообщением `plugins[i] <name>: <path> — <issue>`, применение `requires.executeScript` с логом
- [x] 1.4 Тесты `test/plugins-load.test.mjs`: строка = пара, ошибка формы, неизвестный ключ у строгой схемы, плагин без схемы, подстановка окружения, несуществующий модуль

## 2. Виртуальные страницы и хуки в сборке

- [x] 2.1 `core/plugins/tree.ts`: `addPage()` — вычисление `dir`/`level`/`parent`, обновление `descendants`, вставка в конец поддерева родителя (DFS), автосоздание промежуточных узлов-оглавлений, ошибка при коллизии с реальной папкой
- [x] 2.2 `core/build.ts`: третий аргумент `plugins`; вызов `afterScan` после `generateTree` (по порядку, ошибка с именем плагина), `afterBuild` после выходов; `dispatch.ts` грузит плагины до `build()` и передаёт их
- [x] 2.3 Проверить `render/diagrams.ts` на виртуальном `item.dir` (инклюды, пути вывода, checksum-восстановление из бэкапа) — без `fs`-доступа к несуществующему каталогу
- [x] 2.4 Тесты `test/plugins-tree.test.mjs`: виртуальный раздел в `_sidebar.md` и страницах сайта, в `generateMD`/complete, диаграмма виртуальной страницы рендерится (PlantUML на stdlib), порядок DFS, ошибка хука прерывает сборку

## 3. Ассеты, watch, источники

- [x] 3.1 `core/plugins/assets.ts`: копирование `assets` в `dist/vendor/plugins/<name>/`, пост-инъекция `<link>`/`<script>` в `index.html` (перед `</head>`/`</body>`, фолбэк — конец файла); вызов после `generateWebMD`
- [x] 3.2 `dispatch.ts`: `watchPaths` плагинов добавляются в `node-watch` (массив путей), несуществующие — предупреждение
- [x] 3.3 `util/archive.ts`: вынести `extractZip` из `render/jre.ts` (zip-slip-guard общий), добавить `extractTarGz`; `jre.ts` использует новый модуль
- [x] 3.4 `core/plugins/source.ts`: `resolveSource` — `dir` (существование), `archive` (httpGet с `headers` без пустых значений → `os.tmpdir()/c4builder-src-<sha1>/` через `.tmp`+rename → снятие единственного корневого каталога → `subdir`), кэш `Map` на процесс, ошибки с URL/кодом
- [x] 3.5 Тесты: инъекция в шаблон с/без `</head>`, `resolveSource` на локальном tar.gz/zip-фикстуре и http-сервере из теста (успех, 404, zip-slip)

## 4. Плагин openspec

- [x] 4.1 `plugins/openspec/scan.ts`: сканер store — активные change'ы (артефакты, `.openspec.yaml` построчно, дельты `specs/**/spec.md`, прогресс чекбоксов, max mtime), архив, спеки (одно-/двухуровневые)
- [x] 4.2 `plugins/openspec/render.ts`: сводка (счётчики, таблица по mtime desc), страница change'а (шапка с метаданными и прогрессом; разделы proposal → design → tasks → прочие → дельты; переписывание ссылок на артефакты в якоря; копирование картинок), страницы спек и промежуточных папок, сводка архива
- [x] 4.3 `plugins/openspec/fences.ts`: извлечение ```plantuml/```d2 в `Diagram` (обёртка `@startuml/@enduml`), замена на `![…](name.ext)`
- [x] 4.4 `plugins/openspec/index.ts`: схема опций `{ dir: 'openspec', mount: 'OpenSpec' }` `.strict()`, `watchPaths`, `afterScan` через `addPage`; регистрация в `plugins/index.ts`
- [x] 4.6 Раскладка change'а гибридом: опция `artifacts` (порядок; первый — на странице change'а), подстраницы артефактов и `specs/**` дельт, шапка со ссылками, переписывание ссылок на страницы (`?id=`), картинки к своей странице; обновить README и тест 4.5
- [x] 4.5 Тесты `test/plugin-openspec.test.mjs` на мини-фикстуре store (2 change'а с tasks/дельтами/plantuml, 1 архивный, двухуровневые спеки, кастомный артефакт `plan.md`): sidebar, сводка, прогресс, отрендеренная диаграмма, пустой store, отсутствующий `dir`

## 5. Плагин openapi

- [x] 5.1 `util/glob.ts`: glob → RegExp (`**`, `*`, `{a,b}`) + рекурсивный обход; тест
- [x] 5.2 `vendor/docsify/swagger-ui.css` той же версии, что `swagger-ui-bundle.js` (версия зафиксирована в README «Vendored»); проверить whitelist `files`
- [x] 5.3 `plugins/openapi/index.ts`: схема `{ mount: 'API', dir?, archive?, subdir?, headers?, glob }` `.strict()` + refine «ровно один источник»; `requires.executeScript`; `assets.styles`; `afterScan`: источник → glob → копия спек в `dist/<mount>/_specs/<relpath>` (через `afterBuild`) → страницы swagger-ui + сводка; ошибки: пустое совпадение, коллизии имён; `watchPaths` при `dir`
- [x] 5.4 Тесты `test/plugin-openapi.test.mjs`: локальная папка с 3 спеками и относительным `$ref`, страница без CDN-ссылок, `executeScript` принудительно, пустой glob — ошибка, `dir`+`archive` — ошибка

## 6. Документация и завершение

- [x] 6.1 README: раздел «Plugins» — ключ `plugins`, встроенные `openspec`/`openapi` с опциями и примером для repo с `openspec/` и репо контрактов, контракт стороннего плагина (`definePlugin`, хуки, источники), совместимость со старыми версиями
- [x] 6.2 CLAUDE.md репо: строка про `src/plugins/` и `src/core/plugins/`
- [x] 6.3 `npm run check`, `npm run test:unit`, `npm run test:golden` — эталоны без изменений
- [x] 6.4 Прогон на arch локально (`c4builder --site` с `plugins` в `.c4builder`), проверка sidebar/поиска/диаграмм design.md и раздела API; затем rc-релиз и MR в арх-репо с правкой `.c4builder` — `.c4builder` с плагинами в arch с rc.2 (Pages-сборка в CI); rc.4 сверен с rc.3 на 133 диаграммах arch, регрессий нет

## specs

[Обзор](#C4-Builder)

- [openapi-plugin](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/specs/openapi-plugin/openapi-plugin)
- [openspec-plugin](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/specs/openspec-plugin/openspec-plugin)
- [plugin-system](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plugin-system/specs/plugin-system/plugin-system)

## openapi-plugin

[Обзор](#C4-Builder)

## Purpose

Публикация набора OpenAPI-контрактов на docsify-сайте: страница swagger-ui на каждую спеку из
локальной папки или архива репозитория контрактов, полностью офлайн — без внешних CDN и без
запросов из браузера читателя за пределы сайта.

## ADDED Requirements

### Requirement: Раздел API из набора спек

Встроенный плагин `openapi` SHALL строить раздел сайта под точкой монтирования (`mount`, по
умолчанию `API`) из файлов источника (`dir` либо `archive` — ровно один), отобранных по
`glob` (по умолчанию `**/openapi.{yaml,yml,json}`). На каждую найденную спеку MUST быть
страница с именем родительской папки спеки (для файла в корне источника — имя файла без
расширения); страница-сводка раздела MUST перечислять спеки со ссылками по алфавиту. Пустое
совпадение `glob` MUST прерывать сборку с указанием источника и шаблона.

#### Scenario: Спеки репозитория контрактов
- **WHEN** источник — архив репозитория с `finch/openapi.yaml`, `selling-agent/openapi.yaml`, `common/openapi.yaml`
- **THEN** раздел содержит страницы `finch`, `selling-agent`, `common` и сводку со ссылками на них

#### Scenario: Ни одна спека не найдена
- **WHEN** `glob` не совпадает ни с одним файлом источника
- **THEN** сборка прерывается с сообщением, содержащим источник и шаблон

#### Scenario: Ошибка конфигурации источника
- **WHEN** заданы одновременно `dir` и `archive` либо ни один из них
- **THEN** сборка не стартует, ошибка называет плагин и опции

### Requirement: Страница спеки — офлайн swagger-ui

Страница спеки SHALL отображать её через swagger-ui, подключённый из ассетов сайта (скрипт и
стиль вендорены в пакет и копируются в выходной каталог). Файл спеки MUST копироваться в
выходной каталог, сохраняя относительный путь внутри источника, и загружаться swagger-ui
относительной ссылкой — так относительные `$ref` между спеками продолжают разрешаться. Страница
MUST NOT ссылаться на внешние CDN и MUST NOT требовать доступа к исходному репозиторию у
читателя. Плагин SHALL требовать выполнения скриптов на страницах (`executeScript`).

#### Scenario: Открытие страницы без сети
- **WHEN** собранный сайт открыт в браузере без доступа к интернету и к GitLab
- **THEN** страница спеки отрисовывает swagger-ui с содержимым спеки

#### Scenario: Относительные $ref
- **WHEN** `finch/openapi.yaml` ссылается на `../common/openapi.yaml#/components/schemas/Error`
- **THEN** swagger-ui разрешает ссылку по скопированному рядом файлу `common/openapi.yaml`

#### Scenario: executeScript выключен в конфиге
- **WHEN** в `.c4builder` `executeScript: false`, а плагин `openapi` подключён
- **THEN** сайт собирается с выполнением скриптов, о чём сообщается в логе

### Requirement: Источник — локальная папка или архив без авторизации по умолчанию

Плагин SHALL получать спеки через резолвер источников ядра. Для публичного или
внутренне-видимого репозитория `archive` MUST работать без заголовков авторизации; `headers` — опция.
При `dir` папка SHALL объявляться путём наблюдения для watch-режима; при `archive`
повторные сборки в одном процессе MUST переиспользовать скачанный архив.

#### Scenario: Архив без токена
- **WHEN** задан `archive` на архив репозитория с внутренней видимостью и `headers` не заданы
- **THEN** архив скачивается без заголовка авторизации, страницы строятся

#### Scenario: Локальная папка в watch-режиме
- **WHEN** источник — `dir` и в нём меняется спека при `-w`
- **THEN** сайт пересобирается с обновлённой спекой

## openspec-plugin

[Обзор](#C4-Builder)

## Purpose

Публикация локального OpenSpec-store на docsify-сайте: сводка, активные change'ы, актуальные
спеки и архив как обычные страницы сборки — с поиском, sidebar и локальным рендером диаграмм
артефактов.

## ADDED Requirements

### Requirement: Раздел OpenSpec из локального store

Встроенный плагин `openspec` SHALL строить раздел сайта из папки store (`dir`, по умолчанию
`openspec` относительно текущего каталога) под точкой монтирования (`mount`, по умолчанию
`OpenSpec`) — дочерним разделом корня сайта. Раздел MUST содержать: страницу-сводку,
подраздел активных change'ов, подраздел спек, подраздел архива. Отсутствие папки store MUST
прерывать сборку с указанием пути. Пустой store (без change'ов и спек) SHALL давать раздел с
нулевыми счётчиками, а не ошибку.

#### Scenario: Раздел в sidebar
- **WHEN** в `.c4builder` подключён плагин `openspec` и store содержит change'ы и спеки
- **THEN** sidebar сайта содержит раздел с именем `mount` и вложенные подразделы change'ов, спек и архива

#### Scenario: Переименование раздела
- **WHEN** задано `mount: "Планы"`
- **THEN** раздел и его путь в выходном каталоге используют это имя

#### Scenario: Store не найден
- **WHEN** папка `dir` отсутствует
- **THEN** сборка прерывается с сообщением, содержащим ожидаемый путь

### Requirement: Сводка store

Страница-сводка SHALL показывать число активных change'ов, число спек, число архивных
change'ов и суммарный прогресс задач (выполнено/всего) по активным change'ам, а также
таблицу активных change'ов со ссылкой на страницу каждого, прогрессом его задач и датой
последнего изменения артефактов, отсортированную по дате изменения от новых к старым.

#### Scenario: Прогресс в сводке
- **WHEN** у активного change'а в `tasks.md` 23 пункта-чекбокса, из них 12 отмечены
- **THEN** строка таблицы показывает `12/23`, а суммарный прогресс учитывает эти числа

#### Scenario: Change без tasks
- **WHEN** у change'а нет `tasks.md` или в нём нет чекбоксов
- **THEN** прогресс отображается как отсутствующий (не `0/0` с ошибкой деления), сводка строится

### Requirement: Страница change'а и подстраницы артефактов

Каждая папка внутри `changes/` (кроме `archive/`) SHALL давать страницу с именем папки
(идентификатор change'а) и вложенные подстраницы. Порядок артефактов задаёт опция плагина
`artifacts` (по умолчанию `proposal, design, tasks`): первый артефакт списка, если он есть в
change'е, MUST выводиться прямо на странице change'а; остальные `*.md` корня папки — отдельными
подстраницами с именем артефакта в порядке списка, затем не перечисленные — по алфавиту.
Дельты спек из `specs/**/spec.md` change'а SHALL публиковаться подразделом `specs` со
страницей на дельту, повторяя структуру папок. Шапка страницы change'а MUST содержать
метаданные (схема, дата создания — если есть), прогресс задач и ссылки на все подстраницы.
Пункты `- [ ]`/`- [x]` MUST сохраняться как чекбоксы.

#### Scenario: Полный change
- **WHEN** change содержит `proposal.md`, `design.md`, `tasks.md`, `specs/<путь>/spec.md`
- **THEN** страница change'а показывает шапку с прогрессом, ссылки на подстраницы и текст proposal; в sidebar под change'ем идут `design`, `tasks`, `specs → <путь>`

#### Scenario: Нестандартные артефакты и порядок
- **WHEN** change создан по кастомной схеме и содержит `plan.md`, `notes.md`, а `artifacts: ["plan"]`
- **THEN** `plan` выводится на странице change'а, `notes` — подстраницей; сборка не требует знания схемы

#### Scenario: Ссылки между артефактами
- **WHEN** артефакт ссылается относительной ссылкой на другой артефакт того же change'а (`design.md`, `tasks.md#done`, `specs/<путь>/spec.md`) либо на файл (картинку) в папке change'а
- **THEN** ссылка ведёт на соответствующую страницу сайта (с сохранением якоря), а файл копируется к странице, где на него ссылаются

### Requirement: Диаграммы артефактов рендерятся локально

Блоки кода ```plantuml и ```d2 в артефактах SHALL извлекаться в диаграммы страницы и
рендериться локальным движком сборки в выбранном `diagramFormat`; в тексте на их месте
MUST стоять изображение. Онлайн-сервисы рендера MUST NOT использоваться; клиентский
рендер в браузере для этих блоков MUST NOT срабатывать.

#### Scenario: PlantUML в design.md
- **WHEN** `design.md` содержит блок ```plantuml с C4-диаграммой на stdlib
- **THEN** страница содержит отрендеренное изображение на его месте, а исходный текст блока не отправляется никуда за пределы процесса сборки

#### Scenario: Ошибка синтаксиса диаграммы
- **WHEN** блок диаграммы не компилируется
- **THEN** сборка сообщает об ошибке с идентификатором change'а и именем артефакта по общим правилам рендера

### Requirement: Подраздел спек

Спеки из `specs/` SHALL публиковаться страницами, повторяя структуру папок store (одно- и
двухуровневая раскладка: `specs/<capability>/spec.md` и `specs/<область>/<capability>/spec.md`).
Промежуточные папки SHALL становиться подразделами со списком вложенных спек. Имя страницы —
имя папки capability.

#### Scenario: Двухуровневые спеки
- **WHEN** store содержит `specs/payments/refunds/spec.md`
- **THEN** в sidebar есть `Specs → payments → refunds`, страница показывает содержимое `spec.md`

### Requirement: Подраздел архива

Папки `changes/archive/*` SHALL публиковаться так же, как активные change'ы, в подразделе
архива, отсортированные по имени папки от новых к старым (префикс даты в имени). Сводка
подраздела архива MUST перечислять архивные change'ы со ссылками.

#### Scenario: Архивный change
- **WHEN** в `changes/archive/2026-08-13-dig-33841-ai-answer-disclaimer/` есть артефакты
- **THEN** страница доступна в подразделе архива и не учитывается в счётчике активных change'ов

### Requirement: Watch-режим отслеживает store

Плагин SHALL объявлять папку store как путь наблюдения.

#### Scenario: Правка артефакта при -w
- **WHEN** в watch-режиме меняется `tasks.md` активного change'а
- **THEN** сайт пересобирается, прогресс на странице и в сводке обновляется

## plugin-system

[Обзор](#C4-Builder)

## Purpose

Расширение сборки внешними источниками без правки ядра: плагины, объявленные в `.c4builder`,
добавляют в дерево сборки виртуальные страницы и диаграммы, ассеты сайта и пути наблюдения,
а ядро валидирует их опции и загружает их до старта сборки.

## ADDED Requirements

### Requirement: Плагины объявляются в конфигурации

`.c4builder` SHALL принимать ключ `plugins` — список записей, каждая из которых либо строка
(идентификатор плагина с опциями по умолчанию), либо пара `[идентификатор, объект опций]`.
Идентификатор MUST резолвиться в одном из порядков: встроенный плагин по имени, локальный
модуль по пути относительно текущего каталога, npm-пакет по имени. Значение ключа неверной
формы MUST отклоняться понятной ошибкой с путём ключа при загрузке опций. Отсутствие ключа
SHALL означать пустой список — поведение сборки без плагинов не меняется.

#### Scenario: Строка и пара равнозначны
- **WHEN** в `plugins` указано `"openspec"` либо `["openspec", {}]`
- **THEN** загружается встроенный плагин `openspec` с опциями по умолчанию

#### Scenario: Локальный модуль и npm-пакет
- **WHEN** идентификатор начинается с `./`, `../` или `/`, либо не совпадает со встроенным именем
- **THEN** модуль загружается соответственно по пути от текущего каталога либо как npm-пакет; несуществующий модуль даёт ошибку с идентификатором и причиной

#### Scenario: Неверная форма ключа
- **WHEN** `plugins` — не массив либо содержит запись не строкового и не парного вида
- **THEN** загрузка опций завершается ошибкой, называющей `plugins` и позицию записи

#### Scenario: Совместимость с прежними версиями
- **WHEN** конфиг с ключом `plugins` читает версия без поддержки плагинов
- **THEN** ключ игнорируется, сборка проходит без разделов плагинов

### Requirement: Опции плагина валидируются его схемой до старта сборки

Плагин MAY объявить схему своих опций. Ядро SHALL валидировать опции по ней при загрузке
плагина, до начала сборки; ошибка MUST называть плагин, ключ опции и причину. Дефолты схемы
MUST применяться к отсутствующим опциям. Схема встроенных плагинов MUST быть строгой:
неизвестный ключ опции — ошибка. До валидации в строковых опциях SHALL подставляться
переменные окружения вида `${NAME}`; незаданная переменная даёт пустую строку.

#### Scenario: Ошибка типа опции
- **WHEN** опция плагина имеет неверный тип
- **THEN** сборка не стартует, ошибка содержит имя плагина, ключ и ожидаемый тип

#### Scenario: Неизвестная опция встроенного плагина
- **WHEN** в опциях встроенного плагина есть ключ, не описанный схемой (например, опечатка)
- **THEN** сборка не стартует, ошибка называет неизвестный ключ

#### Scenario: Плагин без схемы
- **WHEN** сторонний плагин не объявляет схему опций
- **THEN** опции передаются ему без изменений

#### Scenario: Подстановка окружения
- **WHEN** опция содержит `${GITLAB_TOKEN}` и переменная задана
- **THEN** плагин получает опцию с подставленным значением, а значение не попадает в вывод сборки и логи

### Requirement: Виртуальные страницы через хук после скана

Ядро SHALL вызывать хук плагина `afterScan` после построения дерева исходников и до рендера,
передавая дерево и опции сборки. Плагин MAY добавить в дерево виртуальные элементы —
страницы с markdown-содержимым и диаграммами, не имеющие файлов в каталоге исходников.
Виртуальные элементы MUST проходить штатные фазы наравне с реальными: рендер их диаграмм
локальным движком, генерация страниц сайта и markdown, sidebar, поиск сайта, complete-документ.
Порядок вызова хуков SHALL совпадать с порядком записей `plugins`; ошибка хука MUST прерывать
сборку с именем плагина.

#### Scenario: Виртуальный раздел на сайте
- **WHEN** плагин добавил виртуальные элементы под точкой монтирования
- **THEN** в собранном сайте есть их страницы и записи sidebar на соответствующем уровне вложенности, а поиск сайта находит их текст

#### Scenario: Диаграммы виртуальных страниц рендерятся локально
- **WHEN** виртуальный элемент содержит диаграмму PlantUML
- **THEN** она рендерится тем же локальным движком, что диаграммы из исходников, и попадает в страницу как изображение; онлайн-сервисы не используются

#### Scenario: Виртуальные страницы в остальных выходах
- **WHEN** включены `generateMD` и/или `generateCompleteMD`
- **THEN** виртуальные страницы присутствуют в этих выходах наравне с реальными

#### Scenario: Ошибка плагина
- **WHEN** хук плагина бросает исключение
- **THEN** сборка прерывается с сообщением, содержащим имя плагина и текст ошибки; бэкап предыдущей сборки сохраняется по общим правилам

### Requirement: Ассеты плагинов и хук после сборки

Ядро SHALL вызывать хук `afterBuild` после генерации выходов, передавая путь выходного
каталога и опции. Плагин MAY объявить скрипты и стили для сайта: ядро MUST скопировать их в
выходной каталог и подключить в `index.html` пост-обработкой готового HTML — независимо от
того, используется ли пользовательский `docsifyTemplate`. Плагин MAY потребовать включения
`executeScript`; тогда сборка ведёт себя как при `executeScript: true`.

#### Scenario: Ассеты при пользовательском шаблоне
- **WHEN** сайт собирается с `docsifyTemplate` из репозитория и плагин объявил стиль и скрипт
- **THEN** `index.html` содержит подключения этих ассетов, а сами файлы лежат в выходном каталоге; шаблон править не требуется

#### Scenario: Плагину нужен executeScript
- **WHEN** в конфиге `executeScript: false`, но подключён плагин, требующий выполнения скриптов на страницах
- **THEN** сайт собирается с выполнением скриптов, в лог выводится сообщение о причине

### Requirement: Плагины участвуют в режиме наблюдения

Плагин MAY объявить дополнительные пути наблюдения. В watch-режиме изменения по этим путям
MUST вызывать пересборку так же, как изменения в каталоге исходников.

#### Scenario: Изменение вне каталога исходников
- **WHEN** запущен `--site -w` и меняется файл под объявленным плагином путём (например, `openspec/`)
- **THEN** сайт пересобирается и отражает изменение

### Requirement: Источники плагинов — локальная папка или архив

Ядро SHALL предоставлять плагинам резолвер источника: `dir` — путь к локальной папке;
`archive` — HTTP(S)-URL архива tar.gz или zip с опциональными `subdir` и `headers` (карта HTTP-заголовков; пустые значения после подстановки окружения отбрасываются). Результат
резолва — локальный каталог; для `archive` ядро MUST скачать и распаковать архив в кэш-каталог
внутри процесса сборки. В watch-режиме архив SHALL скачиваться один раз на процесс.
Недоступный источник MUST прерывать сборку с URL/путём и причиной. Распаковка MUST отвергать
записи с путями вне целевого каталога.

#### Scenario: Локальная папка
- **WHEN** источник задан как `dir`
- **THEN** плагин получает путь к этой папке; отсутствие папки — ошибка с указанием пути

#### Scenario: Архив по HTTP
- **WHEN** источник задан как `archive` с URL tar.gz
- **THEN** архив скачивается (с заданными непустыми `headers`), распаковывается, и плагин получает путь к каталогу `subdir` внутри распакованного архива

#### Scenario: Архив в watch-режиме
- **WHEN** сборка в режиме `-w` перезапускается после правки исходников
- **THEN** ранее скачанный архив не скачивается повторно

#### Scenario: Недоступный архив
- **WHEN** запрос архива завершается ошибкой HTTP или сети
- **THEN** сборка прерывается с URL и кодом/причиной, без частичного раздела на сайте

## 2026-10-03-plantuml-1-2026-8

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="10" max="10"></progress> 10/10 (100%) · **Updated:** 2026-10-06

[tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-plantuml-1-2026-8/tasks/tasks)

# Обновление вендорного PlantUML 1.2025.2 → 1.2026.8

## Why

В Smetana-раскладке наконечники залитых декораций (`>>`, ими рисует связи `Rel` из
C4-PlantUML) выходят незалитыми. Наш апстрим-фикс plantuml/plantuml#2796 (коммит
`0b22e23`) влит 2026-07-25 и вошёл в релизы `v1.2026.7` и `v1.2026.8`, так что issue #14
больше ничем не заблокирован. Берём последний стабильный релиз и закрываем issue до финального 0.4.0.

## What Changes

- `vendor/plantuml-1.2025.2.jar` → `vendor/plantuml-1.2026.8.jar`. Сборка та же: полный
  GPL-JAR `plantuml-1.2026.8.jar` из релиза, sha256
  `5e1ecfa8ecd32c90b03bbf3b1eb6f020943f98ab0fcf4032be31a0002ee2c462`.
- `VENDORED_JAR` в `src/util/utils.ts` → `1.2026.8`, это единственная точка правды для
  версии и имени JAR.
- Golden-эталоны пересняты (`UPDATE_GOLDEN=1`). Дифф эталонов — это и есть визуальный
  аудит: ожидаем залитые наконечники связей и прочие апстрим-изменения рендера.
- Строка в README, changelog `## Unreleased`.

Видимое поведение: у всех PlantUML-диаграмм меняется рендер (стрелки и возможные
апстрим-сдвиги раскладки). Перерендер у пользователей произойдёт сам: версия JAR входит в
ключ чексуммы кэша (`renderKey` в `diagrams.ts`), `--reset` не нужен.

## Capabilities

### New Capabilities

Нет.

### Modified Capabilities

Нет. Требования `diagram-rendering` («единственный вендорный JAR», «легаси-ключ версии»)
к номеру версии не привязаны и не меняются. В `.openspec.yaml` стоит `skip_specs: true`.

## Impact

- `vendor/`: JAR 21.7 МБ → 29.9 МБ (+8 МБ в npm-пакете и docker-образе).
- `src/util/utils.ts`: `VENDORED_JAR`.
- `test/golden/*`: пересъёмка эталонов.
- Легаси-ключ: у `.c4builder` с `plantumlVersion: "1.2025.2"` теперь будет печататься
  однократное предупреждение (пин ≠ вендорной версии). Так и задумано по спеке. У `arch`
  стоит `latest`, его это не касается.
- Java: JRE-резолвер требует ≥ 17 и качает Temurin 21. Ядро PlantUML собрано под Java 11 и работает
  на JRE 17; только ELK (`!pragma layout elk`) и openpdf требуют Java 21, c4builder рендерит через Smetana.
- ditaa рендерится тем же JAR (без `-Playout=smetana`), он покрыт `ditaa.puml` в шаблоне,
  а значит и golden.
- Релизный путь: rc.4, затем прогон на `arch` (задача 6.4 `plugin-system`), затем финальный 0.4.0.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Обновление JAR

- [x] 1.1 Скачать `plantuml-1.2026.8.jar` из релиза `v1.2026.8`, сверить sha256 `5e1ecfa8…c462`, положить в `vendor/` вместо `plantuml-1.2025.2.jar`; в `vendor/` ровно один PlantUML-JAR
- [x] 1.2 Проверить совместимость с JRE ≥ 17 (минимум резолвера): `Build-Jdk-Spec: 21`, но ядро PlantUML собрано под Java 11 и работает на JRE 17; байткод Java 21 только у ELK (`!pragma layout elk`) и openpdf, а c4builder рендерит через Smetana. `MAJOR_MIN` не меняем
- [x] 1.3 `VENDORED_JAR` в `src/util/utils.ts` → `1.2026.8`; `grep -rn 1.2025.2 src test` пуст; `npm run build` и `npm run check` зелёные

## 2. Регрессия рендера

- [x] 2.1 `npm run test:unit` зелёный
- [x] 2.2 `UPDATE_GOLDEN=1 npm run test:golden`, затем просмотр диффа эталонов: наконечники связей C4 залиты, кириллица и ditaa на месте, нет пустых или битых SVG; повторный `npm run test:golden` без UPDATE зелёный
- [x] 2.3 Строка в README changelog `## Unreleased`: PlantUML обновлён до 1.2026.8 (залитые наконечники `>>` в Smetana, closes #14)

## 3. Релиз

- [x] 3.1 PR в `master`, CI зелёный (включая golden на пиновом runner), merge закрывает #14 — PR #21; `audit` падал на свежих advisories рантайм-зависимостей, починено в PR #22
- [x] 3.2 `npm version prerelease` → `v0.4.0-rc.4`, push тега; npm dist-tag `rc` = 0.4.0-rc.4
- [x] 3.3 Прогон rc.4 на `arch` (`c4builder --site`): диаграммы рендерятся, стрелки залиты; закрывает задачу 6.4 `plugin-system`
- [x] 3.4 Финальный релиз: `## Unreleased` → `## v0.4.0`, `npm version 0.4.0`, push тега; npm `latest` = 0.4.0

## 2026-10-03-offline-site-assets

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="14" max="14"></progress> 14/14 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/specs/specs)

## Why

Контракт c4builder — «рендер только локальный, онлайн-сервисы не использовать», но
docsify-сайт, который он генерирует для любого пользователя, ходит во внешний мир прямо из
браузера читателя: вендорная тема `vue.css` начинается с `@import` Google Fonts, docsify
превращает `:emoji:` в картинки с `github.githubassets.com`, плагин `docsify-plantuml`
отправляет текст блоков ```` ```plantuml ```` со страниц на `www.plantuml.com` (утечка
содержимого диаграмм из корпсреды), а swagger-ui плагина `openapi` по умолчанию показывает
бейдж `validator.swagger.io` с адресом спеки. Нашли при сборке собственного сайта
документации — там это обойдено отдельным шаблоном `docs/docsify-template.mjs`; чинить нужно
в продукте, для всех.

## What Changes

- **Встроенный шаблон `index.html` без внешних ресурсов**: не подключает
  `docsify-plantuml`, включает родные emoji (`nativeEmoji`) вместо картинок GitHub.
  Параметр `nativeEmoji: true` передаётся в объекте опций шаблона, так что и
  пользовательские шаблоны, сериализующие опции в `window.$docsify`, получают его.
- **Тема без Google Fonts**: при копировании вендорных ассетов в выходной каталог из
  `vue.css` вырезается `@import` шрифтов (вендорный файл не меняется); шрифты —
  системный fallback из той же темы.
- **Блоки ```` ```plantuml ```` в markdown-страницах рендерятся при сборке** локальным
  движком (тот же экстрактор, что у плагина `openspec`, переносится в ядро): на месте блока —
  изображение, в выходах блока нет, так что клиентский `docsify-plantuml` (даже в
  пользовательском шаблоне вроде арх-репо) рендерить нечего. Другие языки
  (```` ```puml ````, ```` ```d2 ````) не трогаются — это принятая форма «показать исходник
  как код».
- **swagger-ui плагина `openapi` без внешнего валидатора** (`validatorUrl: null`).
- **Автотест «в собранном сайте нет внешних адресов»**: сканирует `index.html`, CSS и
  страницы собранного шаблонного проекта на `http(s)://` и `//host` вне allow-листа.
- `vendor/docsify-plantuml.min.js` по-прежнему копируется в выход: пользовательские шаблоны,
  которые его подключают, не получают 404.
- Сайт документации переходит на встроенный шаблон, его обход внешних ресурсов удаляется.

## Capabilities

### New Capabilities
- `offline-site`: собранный docsify-сайт при конфигурации по умолчанию не обращается к
  внешним доменам; ```` ```plantuml ````-блоки страниц рендерятся при сборке; автопроверка.

### Modified Capabilities
- `openapi-plugin`: страница спеки не обращается к внешнему валидатору swagger-ui.

## Impact

- `src/core/compose/docsify.template.ts`, `src/core/compose/markdown.ts` (опции шаблона,
  копирование вендора с правкой `vue.css`), `src/core/scan/tree.ts` (извлечение блоков
  страниц), перенос `src/plugins/openspec/fences.ts` в ядро, `src/plugins/openapi/index.ts`.
- Golden: меняются `index.html` и `vendor/vue.css` во всех эталонах — переснять осознанно.
- Арх-репо (свой `docsifyTemplate` с `docsify-plantuml`, `webTheme` → `vendor/vue.css`):
  правок не требует, утечка закрывается сборкой; блок ```` ```puml ```` в нём остаётся кодом.
- `docs/` сайта, `CHANGELOG.md`, скилл `c4builder` (раздел о диаграммах в страницах).
- Новых npm-зависимостей нет.

## design

[Обзор](#C4-Builder)

# Design

## Context

Мотивация — см. proposal.md. Что определяет подход:

- **Шаблон.** `index.html` пишет `generateWebMD` (`compose/markdown.ts`): встроенный
  `compose/docsify.template.ts` или пользовательский `docsifyTemplate` получает объект опций
  и обычно сериализует его в `window.$docsify` целиком (так делает и шаблон арх-репо).
  Встроенный подключает `vendor/docsify-plantuml.min.js`; ссылка на тему — `options.stylesheet`
  (`webTheme`, по умолчанию `vendor/vue.css`; unpkg-адрес старых конфигов уже маппится на
  вендор в `cli/dispatch.ts`).
- **Вендор.** `vendor/docsify/*` копируется в `dist/vendor/` как есть (`fsextra.copy`).
  `vue.css` начинается с `@import url("https://fonts.googleapis.com/...")`; шрифтовые стеки
  темы уже имеют системный fallback (`Helvetica Neue, Arial, sans-serif`, `Monaco, courier,
  monospace`) и стек emoji-шрифтов для `.emoji`. Вендорный docsify поддерживает
  `nativeEmoji`. `docsify-plantuml` обрабатывает только `pre[data-lang="plantuml"]` и
  шлёт текст на `//www.plantuml.com/plantuml/svg/`.
- **Блоки в страницах.** Сканер (`scan/tree.ts`) кладёт `.md` в `item.mdFiles` как есть —
  ```` ```plantuml ```` доживает до браузера. У плагина `openspec` уже есть экстрактор
  (`plugins/openspec/fences.ts`): блок → диаграмма страницы (`<base>-<sha1>.<ext>`, флаг
  `soft`) + ссылка `![f](f)` на его месте, которую compose заменяет картинкой
  (`diagramRefRegex`). Мягкий отказ `soft` уже реализован в `render/diagrams.ts`.
- **swagger-ui** (`plugins/openapi`): `SwaggerUIBundle({ url, dom_id })` — `validatorUrl` по
  умолчанию `https://validator.swagger.io/validator`.
- Прототип для своего сайта — `docs/docsify-template.mjs` (тема инлайном без `@import`,
  `noEmoji`, без `docsify-plantuml`) плюс язык страницы и ссылка на лендинг.

## Goals / Non-Goals

**Goals:**
- Ноль автоматических внешних запросов у сайта с конфигурацией по умолчанию.
- Закрыть утечку исходников диаграмм и для пользовательских шаблонов (арх-репо) без их правки.
- Видимое поведение страниц сохраняется: что рендерилось картинкой — остаётся картинкой.

**Non-Goals:**
- Проверка пользовательских `webTheme`/`docsifyTemplate` с внешними адресами — явный выбор
  пользователя; не запрещаем и не переписываем.
- Режим `generateLocalImages: false` (диаграммы ссылками на `plantumlServerUrl`) — это
  явное согласие на внешний рендер; поведение не меняется.
- Переписывание вендорных JS (строки с внешними адресами внутри `docsify.min.js`,
  `swagger-ui-bundle.js` остаются — их поведение отключается конфигурацией).

## Decisions

1. **Шаблон: убрать `docsify-plantuml`, добавить `nativeEmoji: true` в объект опций.**
   Опция живёт в общем объекте, который `generateWebMD` передаёт любому шаблону, — шаблоны,
   сериализующие опции, получают её без правок. *Альтернативы:* `noEmoji` (как в прототипе) —
   `:smile:` станет текстом, хуже для читателя; вендорить картинки emoji — тысячи файлов.
   Ключ `plantuml: { skin }` в опциях оставляем — пользовательские шаблоны могут на него
   опираться, вреда нет.
2. **`vue.css` правится при копировании вендора, а не в `vendor/`.** После `fsextra.copy`
   ведущий `@import url(...)` вырезается из `dist/vendor/vue.css` (тот же regex, что в
   прототипе). Вендорные файлы руками не правим (правило репо), а повторное вендорение
   вернуло бы `@import`. Действует и для пользовательских шаблонов, если `webTheme` —
   вендорная тема.
3. **Экстрактор блоков переезжает в ядро и параметризуется языками.** `fences.ts` →
   `src/core/scan/fences.ts`; `createFenceExtractor(langs)`. Плагин `openspec` вызывает его с
   прежним набором (`plantuml`, `puml`, `d2`) — его поведение не меняется. Сканер для обычных
   `.md` вызывает с набором `{plantuml}`: ровно то, что раньше отправлял браузер.
   `base` — имя `.md`-файла без расширения, `source` — путь `.md` от cwd (для предупреждения),
   диаграммы — `soft`, добавляются в `item.diagrams` до сортировки. Относительные
   `!include` в блоке резолвятся от каталога страницы — как у соседнего `.puml`.
   *Альтернативы:* только убрать скрипт из шаблона — диаграммы у пользователей встроенного
   шаблона молча превратятся в код, а арх-репо (свой шаблон со скриптом) продолжит утечку;
   извлекать и `puml`/`d2` — превратит примеры исходников (так их пишут сайт документации и
   арх-репо) в картинки, а `d2`-блоки браузер никогда не рендерил.
4. **Извлечение — в скане, общее для всех выходов.** markdown-коллекция и complete-markdown
   тоже получают картинку вместо блока (переносимо: GitHub/GitLab без PlantUML-интеграции блок
   не рендерят), `llms-full.txt` — исходник блока через существующую ветку «диаграмма страницы».
   *Альтернатива:* только для website — второй путь compose ради одного выхода.
5. **swagger-ui: `validatorUrl: null`** в вызове `SwaggerUIBundle`.
6. **Проверка — по golden-эталону `default`, без новой сборки.** Golden-тест уже гарантирует,
   что `test/golden/default/tree` = фактический выход шаблонного проекта; новый тест
   `test/offline-site.test.mjs` сканирует там `index.html`, `*.css` и `*.md` на
   `https?://` и `url(//…)`/`src="//…"`: в `index.html`/CSS — любое вхождение (кроме значения
   ключа `repo` в `$docsify` — это ссылка-уголок, не загрузка), в `.md` — только в
   изображениях (`![…](http…)`, `<img src=…>`). Вендорные `.js` не сканируются (см. Non-Goals).
   Блоки в страницах проверяются отдельным тестом на временном проекте (spawn CLI, как
   `llms.test.mjs`; рендер — системной java, как `check.test.mjs`).
7. **Сайт документации — на встроенном шаблоне + минимальная обёртка.** Из
   `docs/docsify-template.mjs` уходят инлайн темы и `noEmoji`; остаются `lang` и `nameLink`
   (специфика сайта), тема — `<link>` на `vendor/vue.css`.

## Risks / Trade-offs

- [Кто-то показывает исходник через ```` ```plantuml ```` как код] → станет картинкой.
  Решение: в CHANGELOG и на странице «Диаграммы» — «для исходника используйте `puml`/`text`».
  **BREAKING** в смысле вывода, отмечаем в changelog.
- [Шрифт темы меняется на системный] → визуально мелкая разница (Source Sans Pro → Helvetica/
  Arial); golden `index.html`/`vue.css` переснимаются осознанно.
- [GitLab с PlantUML-интеграцией рендерил блоки в markdown-коллекции сам] → теперь картинка
  из сборки: тот же результат, без зависимости от настроек GitLab.
- [nativeEmoji не знает редкий shortcode] → остаётся текстом `:code:`, без запроса наружу.

## Migration Plan

Пользователям ничего делать не нужно: правка в выходе сборки. Арх-репо после обновления
образа получает закрытую утечку без правки своего шаблона. Откат — предыдущая версия.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Экстрактор блоков в ядре

- [x] 1.1 Перенести `src/plugins/openspec/fences.ts` в `src/core/scan/fences.ts`, `createFenceExtractor(langs)` с набором языков (design §3); плагин `openspec` вызывает с `plantuml`, `puml`, `d2`, импорты (включая `test/plugin-openspec-fences.test.mjs`, `test/dist.mjs`) обновить. Проверка: `npm run build && npx vitest run test/plugin-openspec-fences.test.mjs test/plugin-openspec.test.mjs` зелёные без изменения ожиданий.
- [x] 1.2 `scan/tree.ts`: для каждого `.md` страницы — `extract(content, <stem .md>, <путь .md от cwd>)` с набором `{plantuml}`, извлечённые диаграммы (`soft: true`) — в `item.diagrams` до сортировки, контент — с заменой блока на ссылку. Проверка: новый `test/page-fences.test.mjs` (spawn CLI на temp-проекте, рендер системной java как в `check.test.mjs`): блок ```` ```plantuml ```` в `src/README.md` → в выходе сайта, markdown-коллекции и complete-markdown картинка и нет текста блока; ```` ```puml ```` и ```` ```d2 ```` остаются кодом; битый блок → код 0, предупреждение с путём `.md`; относительный `!include ../x.iuml` в блоке резолвится от каталога страницы.
- [x] 1.3 Проверить связку с `llms-full.txt`: блок страницы попадает туда исходником в fence `plantuml`. Проверка: кейс в `test/page-fences.test.mjs` с `generateLLMS: true`.

## 2. Шаблон и тема без внешних ресурсов

- [x] 2.1 `compose/docsify.template.ts`: убрать `<script src="vendor/docsify-plantuml.min.js">`; в объект опций `generateWebMD` (и `DocsifyOptions`) добавить `nativeEmoji: true`; копирование `vendor/docsify` в выход сохранить целиком (`docsify-plantuml.min.js` остаётся для пользовательских шаблонов). Проверка: `node dist/index.js` на шаблонном проекте → в `index.html` нет `docsify-plantuml`, есть `"nativeEmoji": true`, файл `vendor/docsify-plantuml.min.js` в выходе есть.
- [x] 2.2 После копирования вендора вырезать ведущий `@import url(...)` из `dist/vendor/vue.css` (design §2). Проверка: в выходе `vue.css` без `fonts.googleapis`, `git diff vendor/` пуст.
- [x] 2.3 Ручная проверка в браузере (devtools → Network) собранного шаблонного проекта: нет запросов к внешним доменам, `:smile:` на временной странице показан символом, шрифты системные. Проверка: отметка в отчёте с перечнем увиденных доменов (должен быть только localhost).

## 3. openapi без валидатора

- [x] 3.1 `plugins/openapi/index.ts`: `SwaggerUIBundle({ url, dom_id, validatorUrl: null })`. Проверка: `test/plugin-openapi.test.mjs` — ожидание строки инициализации с `validatorUrl: null`; тест зелёный.

## 4. Автопроверка и golden

- [x] 4.1 `npm run test:golden:update`: осознанно переснять `index.html` и `vendor/vue.css` во всех вариантах (`default`, `links-top`, `embed-png`). Проверка: `git diff --stat test/golden` — меняются только эти файлы и их строки в `manifest.json`; страницы `.md`, `.svg`, `llms*.txt` без изменений (SVG-шум fontconfig на Arch не коммитить).
- [x] 4.2 `test/offline-site.test.mjs` по design §6: скан `test/golden/default/tree` (`index.html`, `**/*.css`, `**/*.md`), исключение — значение `repo` в `$docsify`, в `.md` — только адреса в изображениях; сообщение называет файл и адрес. Проверка: тест зелёный; временная вставка `<script src="https://cdn.example/x.js">` во встроенный шаблон + `test:golden:update` даёт красный тест с `index.html` и адресом (откатить).
- [x] 4.3 Полный прогон: `npm run build`, `npm test`, `npm run check`, `openspec validate offline-site-assets --strict` — всё зелёное.

## 5. Актуализация

- [x] 5.1 Сайт документации: `docs/docsify-template.mjs` — убрать инлайн темы и `noEmoji`, тема через `<link href="${options.stylesheet}">`, оставить `lang` и `nameLink` (design §7). Проверка: сборка `docs/ru` и `docs/en` → код 0; в `dist/index.html` и `dist/vendor/vue.css` нет внешних адресов.
- [x] 5.2 Страницы сайта RU и EN: «03 Диаграммы» — блоки ```` ```plantuml ```` в страницах рендерятся при сборке, ```` ```puml ````/```` ```text ```` — для показа исходника; «04 Выводы» или «02 Проект» — сайт работает без интернета (что именно не загружается извне), оговорка про `generateLocalImages: false`; «06 Плагины» — openapi без валидатора. Проверка: `npx vitest run test/docs-parity.test.mjs` зелёный, сборка RU/EN → 0.
- [x] 5.3 `skills/c4builder` (`SKILL.md` или `references/diagrams.md`): блоки ```` ```plantuml ```` в `.md` рендерятся при сборке, исходник показывать через `puml`; `template/AGENTS.md` — без изменений, если там нет упоминания блоков. Проверка: `npx vitest run test/skills.test.mjs` зелёный.
- [x] 5.4 `CHANGELOG.md`, `## Unreleased`: сайт без внешних запросов (шрифты, emoji, клиентский PlantUML, валидатор swagger-ui); **BREAKING (вывод):** блоки ```` ```plantuml ```` в страницах теперь картинки во всех выходах, для исходника — `puml`/`text`. Проверка: ревью глазами.

## specs

[Обзор](#C4-Builder)

- [offline-site](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/specs/offline-site/offline-site)
- [openapi-plugin](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-offline-site-assets/specs/openapi-plugin/openapi-plugin)

## offline-site

[Обзор](#C4-Builder)

# Spec Delta

## Purpose

Сайт, собранный c4builder, открывается и работает без интернета и ничего не отправляет за
пределы своего адреса: ни шрифты, ни emoji, ни исходники диаграмм не уходят на внешние сервисы.

## ADDED Requirements

### Requirement: Сайт по умолчанию не обращается к внешним доменам
Собранный docsify-сайт при встроенном шаблоне и теме по умолчанию (`webTheme: vendor/vue.css`) MUST NOT содержать в `index.html`, подключаемых CSS и сгенерированных страницах ссылок на ресурсы внешних доменов (`http://`, `https://`, `//host`), загружаемых браузером автоматически: шрифты, стили, скрипты, изображения. Встроенный шаблон MUST NOT подключать клиентский рендер PlantUML и MUST включать отображение emoji родными символами вместо картинок. Ссылки, которые пользователь сам написал в тексте страниц (обычные гиперссылки), этим требованием не затрагиваются.

#### Scenario: Шаблонный проект без внешних ресурсов
- **WHEN** проект создан `c4builder --new --name demo -y` и собран `c4builder`
- **THEN** в `index.html`, `vendor/*.css` и `.md`-страницах выхода нет адресов внешних доменов, кроме гиперссылок из исходного текста

#### Scenario: Тема без внешних шрифтов
- **WHEN** сайт собран с `webTheme: vendor/vue.css`
- **THEN** скопированный в выход `vendor/vue.css` не содержит `@import` внешних шрифтов, а вендорный файл пакета не изменён

#### Scenario: Emoji без картинок
- **WHEN** страница содержит `:smile:`
- **THEN** сайт показывает символ emoji, не запрашивая изображений с внешних адресов

#### Scenario: Совместимость пользовательского шаблона
- **WHEN** пользовательский `docsifyTemplate` подключает `vendor/docsify-plantuml.min.js`
- **THEN** файл присутствует в выходе (нет 404), сборка проходит, а опции шаблона содержат включённые родные emoji

### Requirement: Блоки PlantUML в страницах рендерятся при сборке
Fenced-блоки с языком `plantuml` в markdown-страницах проекта SHALL извлекаться в диаграммы страницы и рендериться тем же движком и в том же `diagramFormat`, что и файлы `.puml`; на месте блока MUST стоять изображение, а исходный текст блока MUST NOT оставаться в выходах (сайт, markdown, complete-markdown), чтобы клиентский рендер в браузере не мог его отправить. Блоки с другими языками (`puml`, `d2`, прочие) MUST оставаться кодом без изменений. Синтаксическая ошибка в блоке MUST NOT ронять сборку: на месте блока — заглушка, в логе — предупреждение с именем исходного файла.

#### Scenario: Блок plantuml становится картинкой
- **WHEN** `src/README.md` содержит блок ```` ```plantuml ```` с C4-диаграммой на stdlib
- **THEN** в выходах на его месте изображение, отрендеренное локально, и нет текста блока

#### Scenario: Блок puml остаётся кодом
- **WHEN** страница содержит блок ```` ```puml ```` с примером диаграммы
- **THEN** в выходах он остаётся блоком кода с исходным текстом

#### Scenario: Ошибка в блоке
- **WHEN** блок ```` ```plantuml ```` не компилируется
- **THEN** сборка завершается с кодом 0, на месте блока заглушка, предупреждение называет исходный `.md`-файл

#### Scenario: Пользовательский шаблон с клиентским рендером
- **WHEN** проект с пользовательским `docsifyTemplate`, подключающим `docsify-plantuml`, содержит блок ```` ```plantuml ```` в странице
- **THEN** выходная страница не содержит блока `plantuml`, и браузер не обращается к сервису рендера

### Requirement: Автоматическая проверка офлайн-сайта
Тесты SHALL собирать шаблонный проект и проверять отсутствие адресов внешних доменов в `index.html`, CSS и страницах выхода по правилу требования «Сайт по умолчанию не обращается к внешним доменам». Найденный адрес MUST называться в сообщении теста вместе с файлом.

#### Scenario: Регресс ловится тестом
- **WHEN** во встроенный шаблон добавлен `<script src="https://cdn.example/x.js">`
- **THEN** тест падает с сообщением, называющим `index.html` и адрес

## openapi-plugin

[Обзор](#C4-Builder)

# Spec Delta

## MODIFIED Requirements

### Requirement: Страница спеки — офлайн swagger-ui

Страница спеки SHALL отображать её через swagger-ui, подключённый из ассетов сайта (скрипт и
стиль вендорены в пакет и копируются в выходной каталог). Файл спеки MUST копироваться в
выходной каталог, сохраняя относительный путь внутри источника, и загружаться swagger-ui
относительной ссылкой — так относительные `$ref` между спеками продолжают разрешаться. Страница
MUST NOT ссылаться на внешние CDN, MUST NOT обращаться к внешнему валидатору спек (бейдж
валидации swagger-ui выключен) и MUST NOT требовать доступа к исходному репозиторию у
читателя. Плагин SHALL требовать выполнения скриптов на страницах (`executeScript`).

#### Scenario: Открытие страницы без сети
- **WHEN** собранный сайт открыт в браузере без доступа к интернету и к GitLab
- **THEN** страница спеки отрисовывает swagger-ui с содержимым спеки

#### Scenario: Относительные $ref
- **WHEN** `finch/openapi.yaml` ссылается на `../common/openapi.yaml#/components/schemas/Error`
- **THEN** swagger-ui разрешает ссылку по скопированному рядом файлу `common/openapi.yaml`

#### Scenario: executeScript выключен в конфиге
- **WHEN** в `.c4builder` `executeScript: false`, а плагин `openapi` подключён
- **THEN** сайт собирается с выполнением скриптов, о чём сообщается в логе

#### Scenario: Нет запроса к валидатору
- **WHEN** страница спеки открыта в браузере
- **THEN** swagger-ui не показывает бейдж валидации и не обращается к `validator.swagger.io`

## 2026-10-03-node-22

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="7" max="7"></progress> 7/7 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-node-22/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-node-22/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-node-22/specs/specs)

# Proposal

## Why

Поддержка Node 20 закончилась 30.04.2026, а `engines` по-прежнему `>=20.19`. Требование «не
использовать возможности вне 20.19» держит в коде самописный glob (`src/util/glob.ts`) вместо
стабильного `fs.globSync` и закрывает дорогу зависимостям, которые уже требуют Node 22 (jsdom 30,
следующие релизы `bpmn-auto-layout` для change'а `bpmn-diagrams`). CI и Docker-образ уже
работают на Node 22/24, так что фактически поддерживаемая линейка расходится с декларируемой.

## What Changes

- **BREAKING**: `engines.node` поднимается до `>=22.17` (первая версия линейки 22, где
  `fs.glob`/`fs.globSync` объявлены стабильными). На Node 20 npm предупреждает о
  несовместимости (или отказывает при `engine-strict`).
- Самописный glob `src/util/glob.ts` заменяется на `fs.globSync` из стандартной библиотеки;
  поведение плагина `openapi` (шаблон `glob`, сортировка, пропуск `.git`, `node_modules` и
  выходных каталогов) не меняется.
- Упоминания минимальной версии Node актуализируются: README, `CLAUDE.md`, комментарии в
  коде, страницы сайта `docs/ru` и `docs/en`, скилл `c4builder-setup`, `template/AGENTS.md`;
  запись — в `CHANGELOG.md`.
- CI-матрица (Node 22 и 24) и Docker-образ (`node:24-alpine`) не меняются — они уже
  соответствуют новой границе.

## Capabilities

### New Capabilities
- (нет)

### Modified Capabilities
- `dev-toolchain`: требование «Минимальная поддерживаемая версия Node зафиксирована» —
  граница `>=20.19` меняется на `>=22.17`.

## Impact

- `package.json` (`engines`), `package-lock.json` (корневой `engines`).
- `src/util/glob.ts` — удаляется; `src/plugins/openapi/index.ts` переходит на `fs.globSync`;
  `test/plugins-source.test.mjs` и `test/dist.mjs` — тесты glob переписываются на поведение
  плагина, а не утилиты.
- Документация: README, `CLAUDE.md`, `docs/ru`, `docs/en`, `skills/c4builder-setup/SKILL.md`,
  `template/AGENTS.md`; строка в `CHANGELOG.md`.
- Потребители: арх-репа собирается Docker-образом на Node 24 — не затронута. Локальные
  установки на Node 20 получат предупреждение `EBADENGINE`.
- Change `bpmn-diagrams` зависит от этого change'а.
- Новых npm-зависимостей нет.

## design

[Обзор](#C4-Builder)

# Design

## Context

Мотивация — см. proposal.md. Факты, которые определяют подход:

- CI (`.github/workflows/ci.yml`) уже гоняет матрицу Node 22 и 24, Docker-образ — `node:24-alpine`,
  `publish.yml` — Node 24. Расходится только декларация: `package.json` `engines`, требование
  `dev-toolchain` и тексты (README, `CLAUDE.md`).
- `fs.glob`/`fs.globSync` в линейке 22: добавлены в 22.0, `exclude` с glob-шаблонами — 22.14,
  **стабильны с 22.17** (nodejs/node#57513). Фигурные скобки (`{yaml,yml,json}`) и `**`
  поддерживаются.
- Единственный потребитель `src/util/glob.ts` — плагин `openapi` (`globFiles` дважды: спеки по
  `o.glob` и вся статика `**/*.{yaml,yml,json}`), плюс юнит-тесты `test/plugins-source.test.mjs`
  через `test/dist.mjs`.
- Самописный `globFiles` возвращает posix-пути, сортирует, не заходит в `.git`, `node_modules` и
  выходные каталоги сборки (`outputDirs`).

## Goals / Non-Goals

**Goals:**
- Декларируемая граница Node совпадает с реально поддерживаемой и проверяемой в CI.
- Минус одна самописная утилита — стандартная библиотека вместо мини-glob.

**Non-Goals:**
- Изменение CI-матрицы или базового Docker-образа.
- Переход на другие API Node 22 (`require(esm)`, `node:sqlite` и т.п.) — не нужны.
- Выбор версии jsdom для BPMN — решается в `bpmn-diagrams` (см. риски).

## Decisions

1. **Граница — `>=22.17`, а не `>=22.0` или `>=22.22`.** 22.17 — первая версия, где `fs.glob`
   стабилен: ниже код работал бы с `ExperimentalWarning` в выводе CLI. *Альтернатива `>=22.22`*
   (требование jsdom 30) — привязала бы ядро к опциональной зависимости одного движка; jsdom 29
   (`^20.19 || ^22.13 || >=24`) совместим с `>=22.17`, выбор между ними — в `bpmn-diagrams`.
2. **`fs.globSync` с функцией `exclude`, а не со списком шаблонов.** Пропуск выходных каталогов
   задаётся абсолютными путями (`outputDirs`) — функция сравнивает `path.resolve(root, p)` с
   множеством так же, как сейчас, плюс имена `.git`/`node_modules`. Список шаблонов потребовал бы
   переводить абсолютные пути в относительные к `root` шаблоны и экранировать их.
3. **Пути нормализуются в posix и сортируются** (`p.split(path.sep).join('/')`, `.sort()`):
   `fs.globSync` на Windows отдаёт нативные разделители, а плагин строит имена страниц через
   `path.posix` и копирует статику с сохранением относительных путей.
4. **Тесты glob переносятся на поведение плагина.** Юнит-тесты `globFiles`/`globToRegExp`
   удаляются вместе с утилитой; покрытие сохраняется существующими тестами плагина `openapi`
   (поиск спек по шаблону, ошибка «не найдено ни одной спеки», копирование статики) — при
   необходимости добавляется кейс с выходным каталогом внутри источника (`dir: '.'`).

## Risks / Trade-offs

- [Node glob не заходит в каталоги, начинающиеся с точки; самописный заходил во все, кроме
  `.git`] → спеки в скрытых каталогах (`.foo/openapi.yaml`) перестанут находиться. Принимаем:
  источники контрактов так не раскладывают; фиксируется строкой в changelog.
- [Пользователи на Node 20 получают `EBADENGINE`] → это и есть цель; Docker-образ и npx на
  актуальном Node не затронуты. Changelog помечает изменение как BREAKING.
- [Тексты про «Node ≥ 20.19» разъезжаются по README, сайту, скиллам, `AGENTS.md`] → в tasks —
  финальная группа актуализации с grep-проверкой `20\.19` по репозиторию.

## Migration Plan

Один PR: engines + замена glob + тексты. Откат — revert PR. Релиз — минорная версия с пометкой
BREAKING в changelog (пакет до 1.0).

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Граница Node

- [x] 1.1 `package.json` `engines.node` → `">=22.17"`, `npm install --package-lock-only` обновляет корневой `engines` в `package-lock.json`. Проверка: `node -p "require('./package.json').engines.node"` печатает `>=22.17`; `npm ci && npm run build && npm run test:unit` зелёные
- [x] 1.2 Тексты в репозитории: README.MD (требования к Node, если упоминаются после переписывания в `docs-site`), `CLAUDE.md` (строка стека), комментарий в `Dockerfile` (EOL Node 20 — оставить как обоснование мажора, без противоречия новой границе); строка в `CHANGELOG.md` (`## Unreleased`) с пометкой **BREAKING**. Проверка: `grep -rn "20\.19" --exclude-dir=node_modules --exclude-dir=.claude --exclude-dir=archive .` не находит упоминаний вне `openspec/specs/dev-toolchain` (обновится при архиве) и исторических записей changelog о прошлых версиях (их не переписываем)

## 2. `fs.globSync` вместо `src/util/glob.ts`

- [x] 2.1 `src/plugins/openapi/index.ts`: оба вызова `globFiles` заменить на `fs.globSync(pattern, { cwd: root, exclude })` по design §2–3 (функция `exclude` — `.git`, `node_modules`, абсолютные `outputDirs`; пути → posix, `.sort()`). Проверка: `npm run build`; существующие тесты плагина `openapi` зелёные
- [x] 2.2 Удалить `src/util/glob.ts`, экспорт из `test/dist.mjs` и юнит-тесты `globFiles`/`globToRegExp` в `test/plugins-source.test.mjs`; при отсутствии в тестах плагина `openapi` кейса «выходной каталог внутри источника (`dir: '.'`) не считается источником» — добавить его. Проверка: `grep -rn "util/glob\|globFiles\|globToRegExp" src test` пусто; `npm run test:unit` зелёный; новый кейс падает, если убрать `outputDirs` из `exclude`
- [x] 2.3 Строка в `CHANGELOG.md`: спеки `openapi` в каталогах, начинающихся с точки, больше не находятся (design, риски). Проверка: ревью глазами

## 3. Актуализация

- [x] 3.1 Заменить «20.19» на «22.17» в `skills/c4builder-setup/SKILL.md` (проверка `node --version`) и `template/AGENTS.md` (строка установки) — оба вмержены с `agent-skills`; а также в страницах сайта `docs/ru` и `docs/en` (быстрый старт, установка) с одинаковой правкой в обоих языках. Проверка: grep из 1.2 по всему репозиторию пуст; `npx vitest run test/skills.test.mjs` и проверка паритета RU/EN из `docs-site` зелёные
- [x] 3.2 Интеграция: `npm test` и `npm run check` зелёные на Node 22.17 (локально через `npx -p node@22.17 node …` или nvm) и на Node 24 (CI-матрица). Проверка: CI зелёный, в выводе сборки шаблона нет `ExperimentalWarning`

## specs

[Обзор](#C4-Builder)

- [dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-node-22/specs/dev-toolchain/dev-toolchain)

## dev-toolchain

[Обзор](#C4-Builder)

# Spec Delta

## MODIFIED Requirements

### Requirement: Минимальная поддерживаемая версия Node зафиксирована
`package.json` MUST декларировать `engines.node: ">=22.17"`. Код и рантайм-зависимости MUST NOT требовать возможностей Node, отсутствующих в 22.17; опциональные зависимости, загружаемые только для отдельных движков рендера, MUST быть совместимы с этой границей или давать понятную ошибку с требуемой версией Node.

#### Scenario: Установка на устаревшем Node
- **WHEN** пакет устанавливается на Node ниже 22.17 (в том числе Node 20)
- **THEN** npm сообщает о несовместимости engines (предупреждение, либо отказ при engine-strict)

#### Scenario: Работа на минимальной версии
- **WHEN** CLI запускается на Node 22.17
- **THEN** сборка шаблонного проекта и `c4builder check` выполняются без ошибок и без предупреждений об экспериментальных API Node

## 2026-10-03-llms-txt

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="14" max="14"></progress> 14/14 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/specs/specs)

## Why

Агенты всё чаще читают архитектурную документацию как контекст («от чего зависит сервис X»,
«какие контейнеры в системе Y»). Docsify-сайт c4builder уже отдаёт сырые `.md`, но агенту
нужно найти точку входа и получить всё одним запросом. Де-факто стандарт для этого —
[`llms.txt`](https://llmstxt.org/): оглавление со ссылками на markdown-страницы плюс
`llms-full.txt` с полным текстом. У c4builder почти всё для этого есть: дерево страниц
(sidebar) и complete-markdown. Диаграммы при этом агенту полезнее исходником, чем картинкой:
C4-PlantUML-текст (`Person`, `System`, `Rel`) — это готовая семантическая модель, а SVG
по ссылке агенту ничего не даёт.

## What Changes

- **Новый вывод `llms.txt`** в корне собранного сайта (только при `generateWEB`): имя
  проекта, краткое описание и список страниц со ссылками на их `.md` в порядке и иерархии
  sidebar, включая виртуальные страницы плагинов (`openspec`, `openapi`).
- **`llms-full.txt`** рядом: полный текст всех страниц в порядке sidebar, где каждая
  диаграмма вставлена **исходным текстом** (fenced-блоки `plantuml` / `d2`), а не
  ссылкой на изображение. Локальные `!include`/импорты приводятся один раз в приложении
  в конце файла (общий `styles.iuml` не копируется в каждую диаграмму).
- **Включается ключом `.c4builder`** (имя — в design). В существующих конфигах ключа нет,
  так что сборка арх-реп не меняется до явного включения. В дефолтах `new --yes` и
  wizard'а ключ включён вместе с website.
- Сеть не нужна, golden-эталоны существующих выводов не меняются.

## Capabilities

### New Capabilities
- (нет)

### Modified Capabilities
- `output-formats`: к типам вывода добавляется `llms.txt` / `llms-full.txt` (при
  включённом website), wizard предлагает его в выборе форматов.
- `project-scaffold`: дефолты headless-создания (`new --yes`) включают `llms.txt`.

## Impact

- `src/config/schema.ts`, `defaults`, wizard — новый ключ.
- `src/core/compose/` — генерация `llms.txt` из дерева страниц и `llms-full.txt` с
  исходниками диаграмм (переиспользует сборку complete-markdown и разрешение `!include`
  из рендера).
- Тесты: vitest на структуру `llms.txt` и вставку исходников диаграмм; эталон
  `default` дополняется двумя новыми файлами, остальные эталоны не меняются.
- Документация: раздел о выводах (сайт из change'а `docs-site`; до его реализации —
  README) и changelog.
- Новых npm-зависимостей нет.

## design

[Обзор](#C4-Builder)

## Context

Мотивация — в proposal.md, требования — в `specs/output-formats` и `specs/project-scaffold`.
Что уже есть в коде и на что опирается решение:

- `compose/markdown.ts`: `generateWebMD` пишет страницу каждого элемента дерева в
  `<dist>/<путь от rootFolder>/<item.name | webFileName>.md` и `_sidebar.md` (порядок —
  порядок дерева, фильтр `excludeSidebarFolderByPath`); `generateCompleteMD` собирает
  все страницы в один документ. Обе идут через приватный `compileDocument(md, item,
  options, getDiagram)`, где подстановка диаграммы — **стратегия** `getDiagram`.
- Виртуальные страницы плагинов (`plugins/tree.ts addPage`) встают в дерево до compose,
  fence-диаграммы артефактов OpenSpec — обычные `Diagram` с `content`. Отдельной ветки
  для плагинов не нужно.
- Граф локальных зависимостей уже резолвится для чексуммы кэша: PlantUML —
  `foldIncludes` (`scan/tree.ts`, пропускает `<stdlib>` и URL), D2 — `collectFilesCached`
  (`render/d2renderer.ts`). Оба возвращают «материал» строкой, а не список файлов.
- Конфиг: `defaultConfig` питает `new --yes` и wizard; схема (`config/schema.ts`) даёт
  дефолт отсутствующему ключу; wizard переспрашивает форматы, только если какой-то из
  `generateMD/CompleteMD/WEB` не задан в файле (`readLenientConfig`).
- Golden: вариант `default` собирает шаблон (`styles.iuml` в двух диаграммах, D2 с
  импортом `_c4lib.d2`) и сверяет всё дерево `docs/`.

## Goals / Non-Goals

**Goals:**
- `llms.txt` и `llms-full.txt` одним ключом, без новых зависимостей и сети.
- Ноль изменений вывода для существующих конфигов (arch собирается побайтно так же).
- Один резолвер зависимостей диаграмм на кэш и на llms — без второй копии regex-ов.

**Non-Goals:**
- Абсолютные URL в `llms.txt` (базовый адрес сайта сборке неизвестен).
- Пользовательское описание проекта для blockquote (см. Open Questions).
- Разворачивание OpenAPI-спек в `llms-full.txt`: страница плагина `openapi` попадает
  туда как есть (HTML swagger-ui), сама спека лежит в dist статикой.
- Перекодирование исходников в не-UTF-8 `charset`: исходники читаются как UTF-8.

## Decisions

### Ключ `generateLLMS`, дефолт «вкл» для новых проектов, «выкл» для старых
Имя — в ряду `generateMD`/`generateWEB` (`GENERATE_LLMS` в `BuildOptions`).
`defaultConfig.generateLLMS = true` → `new --yes` пишет `true`, wizard отмечает пункт.
В схеме — **явное исключение** `bool(false)` вместо `bool(defaultConfig.generateLLMS)`
с комментарием: отсутствующий ключ = выкл, иначе существующие `.c4builder` (arch)
внезапно получили бы новые файлы. Это не ломает `project-scaffold` «единый источник
дефолтов»: `new --yes` и wizard по-прежнему берут значение из `defaultConfig`; схема
задаёт поведение *легаси-конфига без ключа* — то же, что уже сделано для PDF-ключей.
Альтернатива «дефолт true везде» — проще на одну строку, но меняет вывод arch и golden.

### Wizard: пункт в чекбоксе форматов, не в условии переспроса
Четвёртый пункт «llms.txt for AI agents (needs website)» в существующем checkbox
`Compilation format`, дефолт — `checkedKey(GENERATE_LLMS, defaultConfig.generateLLMS)`.
`GENERATE_LLMS === undefined` в условие показа вопроса **не** добавляется — иначе
каждый старый конфиг заново прогонял бы wizard. `--list` и `--docs` показывают ключ.

### llms.txt: плоский список, заголовок — путь страницы
Формат llmstxt.org: `# <projectName>`, blockquote, `## Pages`, строки
`- [Путь / Страницы](url)`. Плоский список выбран потому, что парсеры llms.txt
(`llms_txt2ctx` и др.) читают строки `- [..](..)` от начала строки, вложенные списки
теряются; иерархию несёт заголовок `A / B / C`. URL — тот же путь, что ссылка sidebar
(`path.relative(ROOT_FOLDER, item.dir)` + имя веб-файла), плюс `.md`, через
`encodeURIPath`. Фильтр исключений sidebar выносится из `generateWebMD` в общий
предикат, чтобы оглавление и sidebar не разъехались.
Blockquote — фиксированный английский текст: «Architecture documentation built with
c4builder. Pages are markdown; full text with diagram sources (PlantUML/D2):
[llms-full.txt](llms-full.txt).»

### llms-full.txt: тот же composer, что complete-markdown, другая стратегия диаграмм
Тело `generateCompleteMD` выносится в `composeComplete(tree, options, getDiagram):
Promise<string>`; `generateCompleteMD` = запись результата со стратегией
`buildDiagramMarkdown(..., 'complete')` — вывод побайтно прежний (проверяет golden).
`llms-full.txt` = `composeComplete` со стратегией «исходник в fence» + приложение.
Fence адаптивный: `` ` `` × max(3, самая длинная серия обратных кавычек в исходнике + 1)
и язык `plantuml`/`d2` по `diagram.engine`. Код — в `compose/markdown.ts` рядом с
`generateCompleteMD`: переиспользует приватные `compileDocument`/`encodeURIPath` без
новых экспортов и нового модуля. Альтернатива — отдельный генератор страниц для llms:
дублировал бы порядок/состав страниц и разъехался бы с complete.

### Приложение include-файлов вместо инлайна
Локальные зависимости приводятся **один раз** в конце (`## Included files`,
`### <путь>` + fence), строки `!include` в исходниках не трогаются. Инлайн (подстановка
содержимого на место `!include`) копировал бы общий `styles.iuml` в каждую из ~100
диаграмм arch — лишние токены агенту — и требовал бы эмулировать семантику
`!includesub`/`!include_many`. Путь — относительно cwd, posix (как в материале
чексуммы), язык fence по расширению (`.puml/.iuml` → `plantuml`, `.d2` → `d2`, иначе
без языка), порядок — по пути.

### Один резолвер на кэш и llms
- `scan/tree.ts`: из `foldIncludes` выделяется `collectIncludes(content, fileDir,
  searchDir, visited): {abs, content}[]` (DFS-порядок, тот же regex и тот же порядок
  поиска); `foldIncludes` становится маппингом этого списка в материал. Материал MUST
  остаться побайтно прежним — иначе у всех потребителей разом инвалидируется кэш
  картинок (перерендер, не поломка, но лишний).
- `render/d2renderer.ts`: экспорт `d2LocalImports(entryAbs, seed): [abs, content][]`
  (то, что `foldD2Imports` уже считает до склейки); `foldD2Imports` переходит на него.
- Вызов — как в `render/diagrams.ts`: PlantUML `collectIncludes(body, item.dir,
  item.dir, new Set())`, D2 — `d2LocalImports(path.join(item.dir, diagram.dir), body)`.
  Резолв идентичен рендеру, в том числе для виртуальных страниц.

### Место в сборке
В `build.ts` после `generateWebMD`/`injectPluginAssets`: `if (GENERATE_LLMS)` →
при `GENERATE_WEBSITE` пишем оба файла, иначе жёлтое предупреждение
(`generateLLMS требует generateWEB — llms.txt не создан`) и продолжаем. Кеши include
и D2-графа ещё живы (чистятся в `finally`), повторного чтения с диска почти нет.
Watch-режим перегенерирует файлы автоматически — это часть `build()`.

### Тесты
- Golden: в фикстуру `default` добавляется `generateLLMS: true` → эталон `default`
  получает ровно два новых файла (+ manifest); остальные файлы `default` и варианты
  `links-top`/`embed-png` (без ключа) не меняются — это и есть проверка совместимости.
  Отдельный вариант не заводим: он дублировал бы ~380 КБ эталона ради двух файлов.
- Vitest без java: оглавление (порядок, заголовки, кодирование, исключение, виртуальная
  страница), fence-стратегия (адаптивный fence, d2, ditaa), приложение (дедуп, вложенность,
  stdlib, D2), неизменность материала `foldIncludes`/`foldD2Imports` (тест пишется до
  рефакторинга против текущего кода).

## Risks / Trade-offs

- [Рефакторинг `foldIncludes` меняет материал чексуммы] → тест-эталон материала до
  рефакторинга; golden повторной сборки с кэшем (`regression-testing`) ловит остальное.
- [`llms-full.txt` большого проекта — мегабайты] → это его назначение; `llms.txt`
  остаётся лёгкой точкой входа, агент выбирает.
- [Схема и `defaultConfig` расходятся по `generateLLMS` намеренно] → комментарий у
  ключа в схеме + сценарий спеки «легаси-конфиг без ключа»; при следующей ревизии
  дефолтов не «чинить».
- [Golden на Arch может краснеть из-за fontconfig (известно)] → при обновлении эталона
  коммитить только `llms.txt`, `llms-full.txt` и строки manifest для них; SVG-дифф
  чужих файлов — признак окружения, не изменения.
- [Не-UTF-8 `charset`] → исходники в `llms-full.txt` декодируются как UTF-8; известное
  ограничение, вне скоупа.

## Migration Plan

Включение в существующем проекте — `"generateLLMS": true` в `.c4builder` (или
`c4builder config`). Откат — удалить ключ; старые версии c4builder ключ молча
отбрасывают (схема нестрогая), сборка не ломается.

## Open Questions

- Нужен ли ключ для пользовательского описания в blockquote (например, `projectDescription`)?
  Добавляется позже одной строкой схемы, формат и задачи не меняет.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Конфиг: ключ generateLLMS

- [x] 1.1 `defaultConfig.generateLLMS = true` (`config/defaults.ts`); в `config/schema.ts` ключ `generateLLMS: bool(false)` с комментарием «отсутствующий ключ = выкл: легаси-конфиги не меняют вывод» (см. design); `GENERATE_LLMS` в `BuildOptions` и маппинг в `getOptions` (`cli/dispatch.ts`). Проверка: тест в `test/config.test.mjs` — `configSchema.parse({})` даёт `generateLLMS: false`, `{generateLLMS: true}` → `true`, строка вместо булева → ошибка; `npm run test:unit` зелёный
- [x] 1.2 Wizard (`cli/wizard/collect.ts`): четвёртый пункт «llms.txt for AI agents (needs website)» в checkbox `Compilation format` с дефолтом `checkedKey(GENERATE_LLMS, defaultConfig.generateLLMS, 'generateLLMS')` и `conf.set('generateLLMS', …)`; в условие показа вопроса `GENERATE_LLMS` НЕ добавлять. Проверка: в temp-проекте с полным конфигом без `generateLLMS` запуск `node dist/index.js` не показывает wizard (тест по образцу `compose-h1.test.mjs`, spawn CLI с `generateLocalImages: false`)
- [x] 1.3 `--list` (`cli/commands/list.ts`) показывает `generateLLMS`, `--docs` (`cli/commands/help.ts`) описывает ключ одной строкой. Проверка: `node dist/index.js --list` и `--docs` в temp-проекте выводят ключ
- [x] 1.4 `new --yes` пишет `generateLLMS: true` (идёт из `defaultConfig` без правок `new.ts`). Проверка: `node dist/index.js --new --yes --name demo` в temp-каталоге → в `demo/.c4builder` есть `"generateLLMS": true`

## 2. Единый резолвер зависимостей диаграмм

- [x] 2.1 ДО рефакторинга: тест-эталон материала — `foldIncludes` на temp-файлах (вложенный `.iuml`, повтор, `<C4/...>`, URL) и `foldD2Imports` на `.d2` с импортом; ожидаемые строки фиксируются из текущего кода. Экспорт в `test/dist.mjs`. Проверка: тест зелёный на текущем коде
- [x] 2.2 `scan/tree.ts`: выделить `collectIncludes(content, fileDir, searchDir, visited): {abs, content}[]` (DFS, тот же regex/порядок поиска/кэш), `foldIncludes` = маппинг списка в материал. Проверка: тест 2.1 зелёный без изменения ожидаемых строк
- [x] 2.3 `render/d2renderer.ts`: экспорт `d2LocalImports(entryAbs, seed): [abs, content][]` (без входного файла), `foldD2Imports` на нём. Проверка: тест 2.1 зелёный без изменения ожидаемых строк

## 3. Генерация llms.txt / llms-full.txt

- [x] 3.1 `compose/markdown.ts`: вынести тело `generateCompleteMD` в `composeComplete(tree, options, getDiagram)`; `generateCompleteMD` пишет его результат со стратегией `buildDiagramMarkdown(…, 'complete')`. Проверка: `npm run test:golden` — `golden-fixture.md` в эталонах без изменений (на Arch допустим известный SVG-шум fontconfig, md-файлы обязаны совпасть)
- [x] 3.2 Предикат исключения sidebar вынести из `generateWebMD` на уровень модуля; `generateLlmsTxt(tree, options)`: H1 `projectName`, blockquote (текст — в design), `## Pages`, плоские строки `- [A / B](url.md)` в порядке дерева, заголовок корня — `homepageName`, URL как у sidebar + `.md` через `encodeURIPath`. Проверка: vitest в `test/llms.test.mjs` — CLI-сборка temp-проекта (`generateLocalImages: false`): порядок и состав строк = `_sidebar.md`, каждая ссылка (после decodeURI) — существующий файл в `docs/`, кириллица/пробелы кодируются, папка из `excludeSidebarFolderByPath` отсутствует, страница плагина `openspec` (мини-store в фикстуре) присутствует
- [x] 3.3 `generateLlmsFull`: `composeComplete` со стратегией «исходник в fence» (язык по `diagram.engine`, fence = обратные кавычки × max(3, длиннейшая серия в исходнике + 1)) + приложение `## Included files`: объединение `collectIncludes`/`d2LocalImports` по всем диаграммам, дедуп по абсолютному пути, сортировка по относительному (cwd, posix) пути, язык fence по расширению, без локальных инклюдов — без секции. Проверка: тесты в `test/llms.test.mjs` — исходник `.puml` целиком в блоке `plantuml`, нет ссылки на `.svg` диаграммы; при `embedDiagram: true` нет `data:image`; исходник с ```` ``` ```` внутри получает fence из 4 кавычек; общий `.iuml` у двух диаграмм — одна запись; вложенный — обе; `<C4/...>` — нет записи, строка в исходнике; fence-диаграмма OpenSpec-артефакта — блок `plantuml`; D2-импорт — unit-тест `d2LocalImports` (без рендера)
- [x] 3.4 `build.ts`: после `generateWebMD`/`injectPluginAssets` — при `GENERATE_LLMS && GENERATE_WEBSITE` записать `llms.txt` и `llms-full.txt` в корень dist; при `GENERATE_LLMS && !GENERATE_WEBSITE` — жёлтое предупреждение «generateLLMS требует generateWEB», сборка продолжается. Проверка: тест в `test/llms.test.mjs` — `generateWEB: false, generateMD: true, generateLLMS: true` → код 0, предупреждение в stdout, llms-файлов нет; без ключа `generateLLMS` — llms-файлов нет
- [x] 3.5 Документация: в README раздел «The output» — подраздел про `llms.txt`/`llms-full.txt` (ключ, зависимость от website, исходники диаграмм, приложение include-файлов, как включить в существующем проекте); строка в changelog `## Unreleased` (секция в README или в `CHANGELOG.md` — где changelog на момент реализации; если секции нет — создать). Проверка: команды и ключ из раздела совпадают с `--docs`

## 4. Golden и интеграция

- [x] 4.1 В `test/fixtures/default.c4builder.json` добавить `"generateLLMS": true`; `npm run test:golden:update`. Проверка: `git status test/golden` — в `default` новые только `tree/llms.txt`, `tree/llms-full.txt` и их строки в `manifest.json`; `links-top`/`embed-png` и прочие файлы `default` без изменений (SVG-дифф от fontconfig на Arch не коммитить); `llms-full.txt` содержит `styles.iuml` и `_c4lib.d2` в приложении по одному разу
- [x] 4.2 Полный прогон: `npm run check`, `npm test`, `openspec validate llms-txt` — всё зелёное

## specs

[Обзор](#C4-Builder)

- [output-formats](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/specs/output-formats/output-formats)
- [project-scaffold](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-llms-txt/specs/project-scaffold/project-scaffold)

## output-formats

[Обзор](#C4-Builder)

## MODIFIED Requirements

### Requirement: Поддерживаемые типы вывода
Сборка SHALL поддерживать три типа вывода: множественные markdown-файлы
(`generateMD`), единый complete-markdown (`generateCompleteMD`) и website
(`generateWEB`), а также дополнение website для агентов — `llms.txt` и
`llms-full.txt` (`generateLLMS`). PDF-вывод (множественные PDF-файлы и единый
complete-PDF) MUST NOT поддерживаться, а зависимость `md-to-pdf` и связанный
headless-браузер MUST отсутствовать в зависимостях пакета.

#### Scenario: Сборка доступных выходов
- **WHEN** в `.c4builder` включены `generateMD`, `generateCompleteMD`, `generateWEB` и/или `generateLLMS`
- **THEN** сборка формирует соответствующие выходы и не порождает PDF-файлов

#### Scenario: PDF-зависимость отсутствует
- **WHEN** просматриваются зависимости пакета
- **THEN** `md-to-pdf` (и транзитивный headless-браузер) в них отсутствует, файла `pdf.css` в пакете нет

### Requirement: Мастер настройки не предлагает PDF
Интерактивный мастер настройки (`c4builder config`) MUST NOT предлагать PDF-форматы
в выборе типов вывода и MUST NOT спрашивать про пользовательский PDF-CSS. Наличие
или отсутствие PDF-ключей в конфиге MUST NOT влиять на то, показывается ли вопрос
о выборе форматов.

#### Scenario: Выбор форматов в мастере
- **WHEN** пользователь запускает мастер настройки
- **THEN** в списке форматов присутствуют только markdown, complete-markdown, website и `llms.txt`, а вопрос про PDF-CSS не задаётся

#### Scenario: Конфиг без PDF-ключей не ре-триггерит вопрос
- **WHEN** запускается сборка с конфигом, где выбраны форматы, но PDF-ключи отсутствуют
- **THEN** мастер выбора форматов не показывается повторно из-за отсутствия PDF-ключей

## ADDED Requirements

### Requirement: Оглавление llms.txt
При включённых `generateLLMS` и `generateWEB` сборка SHALL записывать в корень
выходного каталога файл `llms.txt` в формате llmstxt.org: заголовок H1 с именем
проекта, blockquote с кратким описанием и ссылкой на `llms-full.txt`, секция H2
со списком страниц `- [заголовок](ссылка)`. Список MUST повторять набор и порядок
страниц sidebar сайта (страницы, исключённые `excludeSidebarFolderByPath`, в него
не входят; виртуальные страницы плагинов — входят). Заголовок страницы MUST быть
её путём от корня через ` / ` (корень — имя главной страницы). Ссылка MUST быть
относительным URL-кодированным путём к markdown-файлу страницы, который реально
лежит в выходном каталоге сайта. Список MUST быть плоским (без вложенных списков).

#### Scenario: Оглавление совпадает с sidebar
- **WHEN** собирается демо-проект шаблона с `generateWEB: true` и `generateLLMS: true`
- **THEN** `llms.txt` перечисляет те же страницы и в том же порядке, что `_sidebar.md`, и каждая ссылка указывает на существующий в выходном каталоге `.md`-файл

#### Scenario: Заголовок — путь страницы
- **WHEN** в проекте есть страница `1 Internet Banking System/API Application`
- **THEN** её строка в `llms.txt` имеет заголовок `1 Internet Banking System / API Application`, а ссылка — URL-кодированный путь к её `.md`

#### Scenario: Исключённая из sidebar папка
- **WHEN** папка указана в `excludeSidebarFolderByPath`
- **THEN** её страницы отсутствуют и в `_sidebar.md`, и в `llms.txt`

#### Scenario: Страницы плагина
- **WHEN** включён плагин, добавляющий виртуальные страницы (например, `openspec`)
- **THEN** эти страницы присутствуют в `llms.txt` на своих местах в порядке sidebar

### Requirement: Полный текст llms-full.txt с исходниками диаграмм
При включённых `generateLLMS` и `generateWEB` сборка SHALL записывать в корень
выходного каталога `llms-full.txt`: текст всех страниц проекта в том же составе и
порядке, что complete-markdown. Каждая диаграмма MUST быть вставлена исходным текстом
в fenced-блок с языком движка (`plantuml` для `.puml`, включая ditaa, и `d2` для `.d2`)
на том же месте, где на странице стоит изображение, а не ссылкой на изображение и не
base64. Представление диаграмм в `llms-full.txt` MUST NOT зависеть от
`diagramFormat`, `embedDiagram`, `includeLinkToDiagram` и `generateLocalImages`.
Fenced-блок MUST оставаться корректным, даже если исходник содержит обратные кавычки.

#### Scenario: PlantUML-диаграмма исходником
- **WHEN** страница содержит `context.puml`
- **THEN** в `llms-full.txt` на месте диаграммы стоит блок ```` ```plantuml ```` с текстом `context.puml` без изменений, а ссылки на `context.svg` нет

#### Scenario: D2-диаграмма исходником
- **WHEN** страница содержит `.d2`-диаграмму
- **THEN** в `llms-full.txt` она представлена блоком ```` ```d2 ```` с её исходным текстом

#### Scenario: Диаграмма из fenced-блока артефакта плагина
- **WHEN** артефакт OpenSpec содержит fenced-блок `plantuml`, превращённый плагином в диаграмму страницы
- **THEN** в `llms-full.txt` на его месте стоит fenced-блок `plantuml` с тем же исходником

#### Scenario: Независимость от настроек изображений
- **WHEN** проект собирается с `embedDiagram: true` и `diagramFormat: png`
- **THEN** `llms-full.txt` не содержит `data:image` и ссылок на PNG диаграмм — только исходники

### Requirement: Локальные include-файлы диаграмм в приложении
`llms-full.txt` SHALL завершаться приложением, где каждый локальный файл, подключённый
диаграммами проекта (PlantUML `!include` и его варианты, D2-импорты `@`/`...@`),
включая вложенные, приведён ровно один раз: путь относительно каталога проекта
(posix-разделители) и fenced-блок с содержимым. Файлы MUST быть упорядочены по пути.
Стандартная библиотека (`!include <…>`) и URL-инклюды MUST NOT разворачиваться и
MUST оставаться строками в исходнике диаграммы. Директивы `!include` в исходниках
диаграмм MUST NOT изменяться. Без локальных инклюдов приложение MUST отсутствовать.

#### Scenario: Общий файл стилей приведён один раз
- **WHEN** две диаграммы подключают один и тот же `styles.iuml`
- **THEN** приложение содержит `styles.iuml` ровно один раз, а исходники обеих диаграмм сохраняют строку `!include`

#### Scenario: Вложенный инклюд
- **WHEN** `a.iuml`, подключённый диаграммой, сам подключает `b.iuml`
- **THEN** приложение содержит оба файла

#### Scenario: stdlib не разворачивается
- **WHEN** диаграмма подключает `!include <C4/C4_Container>`
- **THEN** в приложении нет записи для C4-PlantUML, а строка остаётся в исходнике диаграммы

#### Scenario: D2-импорт
- **WHEN** `.d2`-диаграмма импортирует `_c4lib.d2`
- **THEN** приложение содержит `_c4lib.d2` с его содержимым в блоке `d2`

### Requirement: llms-вывод требует website
При `generateLLMS: true` и выключенном `generateWEB` сборка SHALL завершаться успешно
(код возврата 0), собрав прочие включённые выходы, MUST NOT создавать `llms.txt` и
`llms-full.txt` и MUST печатать предупреждение, что `generateLLMS` требует `generateWEB`.

#### Scenario: Website выключен
- **WHEN** в `.c4builder` `generateLLMS: true`, `generateWEB: false`, `generateMD: true`
- **THEN** markdown собирается, `llms.txt`/`llms-full.txt` отсутствуют, напечатано предупреждение о `generateWEB`, код возврата 0

### Requirement: Конфиг без generateLLMS не меняет вывод
Отсутствие ключа `generateLLMS` в существующем `.c4builder` SHALL означать, что
llms-вывод выключен: выход сборки MUST совпадать с выходом до появления ключа. Отсутствие
ключа MUST NOT приводить к повторному показу вопроса о форматах в мастере настройки.

#### Scenario: Легаси-конфиг собирается как раньше
- **WHEN** собирается проект, в `.c4builder` которого нет `generateLLMS`
- **THEN** `llms.txt` и `llms-full.txt` не создаются, остальные файлы выхода побайтно совпадают с golden-эталоном

#### Scenario: Отсутствие ключа не ре-триггерит мастер
- **WHEN** запускается сборка с конфигом, где форматы выбраны, а `generateLLMS` отсутствует
- **THEN** мастер выбора форматов не показывается повторно из-за отсутствия `generateLLMS`

## project-scaffold

[Обзор](#C4-Builder)

## MODIFIED Requirements

### Requirement: Полный конфиг для headless-сборки
В режиме `--yes` создание проекта SHALL записывать в `.c4builder` полный набор
настроек (типы выходов и их под-опции, формат диаграмм, кодировку, локальный рендер),
достаточный, чтобы последующий запуск `c4builder` собрал проект без интерактивного
wizard'а. Значения по умолчанию для выходов MUST включать website, множественные
markdown и llms-вывод (`generateLLMS: true`), `diagramFormat=svg`, локальный рендер
диаграмм и `UTF-8`.

#### Scenario: Сборка после --yes не спрашивает
- **WHEN** проект создан через `c4builder --new --yes --name demo`, затем в нём
  запущен `c4builder`
- **THEN** сборка проходит без интерактивных вопросов и формирует выходы по
  записанным дефолтам, включая `llms.txt` и `llms-full.txt`

#### Scenario: Интерактивное создание не пишет полный конфиг
- **WHEN** проект создан интерактивно (без `--yes`)
- **THEN** поведение записи `.c4builder` остаётся прежним, а первая сборка ведёт
  пользователя через wizard как раньше

## 2026-10-03-cli-fixes

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="10" max="10"></progress> 10/10 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-fixes/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-fixes/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-fixes/specs/specs)

## Why

При работе над сайтом документации и скиллами агенты нашли в CLI три дефекта, которые бьют
по главному сценарию «агент правит → `c4builder check` → сборка» и по доверию к справочным
командам:

- `c4builder check styles.iuml` падает на любой `.iuml` с макросами C4
  (`UpdateElementStyle`, `Person`…): библиотека проверяется включением в пустую диаграмму без
  C4-stdlib. Из-за этого `.iuml` исключён из pre-commit-хука на сайте, а скиллы и `AGENTS.md`
  учат обходному пути.
- `check` печатает `✗ file: строка N: …`, хотя `--help`, остальной вывод CLI и формат,
  который разбирают агенты и CI, — английские. Документация и скиллы вынуждены пояснять
  «`строка` means "line"».
- `c4builder --docs` (а также `--list` и `--reset`) в папке без проекта создаёт пустые
  `.c4builder` и `.c4builder.cache`: справочная команда оставляет мусор, а следующий
  `c4builder` в этой папке уже считает её проектом.

Плюс мелочь из переноса changelog: ссылки `#docker` и «Plugins» в `CHANGELOG.md` ведут на
разделы README, которых больше нет.

## What Changes

- **`check` для `.iuml`**: обёртка библиотеки подключает C4-stdlib перед самим файлом, так
  что `.iuml` с макросами C4 проверяется в том же контексте, в котором его используют
  диаграммы. Библиотеки без C4 проверяются как раньше.
- **Вывод `check` на английском и стабильного формата**: `✗ <file>: line <N>: <message>`,
  сообщения об использовании и неизвестном расширении — тоже на английском. Остальной
  русский вывод CLI вне скоупа (отдельная задача).
- **Справочные команды без побочных эффектов**: `--docs` не читает и не создаёт конфиг;
  `--list` и `--reset` в папке без `.c4builder` сообщают, что проекта нет, и ничего не
  создают (код 1 для `--list`/`--reset`, 0 для `--docs`).
- **`CHANGELOG.md`**: мёртвые ссылки на разделы README заменяются ссылками на страницы
  сайта в репозитории (`docs/en/src/…`).
- Актуализация: страницы сайта RU/EN, скилл `c4builder`, `template/AGENTS.md`, README
  (строка про `check`), pre-commit-хук снова включает `*.iuml`.

## Capabilities

### New Capabilities
- (нет)

### Modified Capabilities
- `cli-commands`: добавляются требования к `check` (формат вывода, проверка `.iuml` с C4)
  и к справочным командам (`--docs`, `--list`, `--reset` не создают файлов вне проекта).

## Impact

- `src/cli/commands/check.ts` — обёртка `.iuml`, английские сообщения.
- `src/cli/dispatch.ts` — `--docs` до создания `Configstore`; проверка наличия
  `.c4builder` для `--list`/`--reset`.
- Тесты: `test/check.test.mjs` (ожидания `строка` → `line`, новый кейс `.iuml` с C4),
  `test/cli-commands.test.mjs` (справочные команды в пустой папке).
- Документация: `docs/ru/src`, `docs/en/src` (страницы «Диаграммы», «Агенты», «CLI и
  конфигурация»), `skills/c4builder/SKILL.md`, `template/AGENTS.md`, `README.MD`,
  `CHANGELOG.md`.
- Поведение сборки и golden-эталоны не меняются; новых зависимостей нет.
- Совместимость: скрипты, которые грепают `строка` в выводе `check`, перестанут совпадать —
  формат документирован как `line N`, строка в changelog об этом.

## design

[Обзор](#C4-Builder)

# Design

## Context

Воспроизведено на `master` (d1e24ff), `node dist/index.js` в пустых временных каталогах:

- **`.iuml` с C4.** `check.ts` оборачивает библиотеку в `@startuml\n!include <abs>\n@enduml` без
  C4-stdlib. `template/src/styles.iuml` (только `skinparam` + `UpdateElementStyle`) →
  `✗ styles.iuml: Syntax Error? (Assumed diagram type: sequence)`. Корень: контекст C4 задаёт
  потребитель (`.puml` подключает `<C4/...>`, затем стили), а обёртка его не воспроизводит.
  Самодостаточные библиотеки (свой `@startuml` + `!include <C4/C4_Context>`, как 139 `.iuml`
  в арх-репо) проходят и сейчас.
- **Формат ошибки.** `check.ts` собирает `строка ${n}: …`; там же русские «использование:»
  и «неизвестное расширение». Остальной CLI тоже местами выводит русский текст (~45 сообщений
  в 18 файлах: jre, плагины, http, конфиг), а тесты сверяют их буквально.
- **Справочные команды.** `dispatch.ts` создаёт `new Configstore(…, { configPath })` для
  `.c4builder` и `.c4builder.cache` до ветвления по командам; конструктор Configstore пишет
  файл сразу. `--docs` возвращается уже после этого, `--list`/`--reset` читают пустой конфиг.
  Итог в пустом каталоге: `.c4builder` = `{}` и `.c4builder.cache` после каждой из трёх команд.
- **CHANGELOG.** `v0.3.0`: `(see [Docker](#docker))`; `v0.4.0`: `(see «Plugins»)` — разделы
  README, перенесённые на сайт.

## Goals / Non-Goals

**Goals:**
- `check` проходит на корректных `.iuml` с макросами C4 и не меняет результат для остальных.
- Вывод `check` — английский и совпадает с тем, что описано в документации и скиллах.
- `--docs`, `--list`, `--reset` ничего не создают вне проекта.

**Non-Goals:**
- Перевод остального вывода CLI на английский (jre, плагины, конфиг, сборка) — отдельный
  change; здесь только `check`, потому что его формат — контракт для хуков, CI и агентов.
- Номер строки для ошибок внутри `.iuml` (позиция относится к обёртке).
- Проверка `.iuml` через поиск подключающих его `.puml`.

## Decisions

1. **`.iuml`: сначала как сейчас, при ошибке движка — повтор с C4-stdlib.** Повторная обёртка:
   `@startuml`, `!include <C4/C4_Dynamic>`, `!include <C4/C4_Deployment>`, `!include <abs>`,
   `@enduml` — два файла покрывают все уровни C4 (Dynamic тянет Component → Container →
   Context; Deployment — Container), двойное подключение stdlib проверено: проходит. Если
   и повтор падает — печатается ошибка повтора (для не-C4 библиотеки она совпадает с прежней:
   `Error in function definition`).
   *Почему не подключать C4 всегда:* +~1.2 с java на каждую `.iuml` (замер: 1.3 с → 2.5 с),
   а самодостаточные библиотеки (арх-репо — 139 файлов) лишь замедлились бы без пользы.
   *Почему не искать потребителей:* `check` работает без проекта и `.c4builder`, скан
   дерева противоречит этому и не определён для файла вне проекта.
   *Почему не эвристика по именам макросов:* хрупко (пользовательские процедуры, новые
   макросы C4), а повтор по факту ошибки ничего не угадывает.
2. **Английские сообщения только в `check.ts`.** `line ${n}: …`, `usage: c4builder check
   <file...>  (.puml | .iuml | .d2)`, `unsupported extension (expected .puml, .iuml or .d2)`.
   Формат `✗ <file>: line <N>: <message>` фиксируется спекой — на него опираются хуки и агенты.
3. **`--docs` — до создания Configstore**; `--list`/`--reset` при отсутствии файла конфига
   (`fs.existsSync(configPath)`, путь уже учитывает `--config-file`) — сообщение
   `no .c4builder in <cwd> — run inside a project or create one with c4builder new` и
   код 1, без Configstore. Первый запуск `c4builder`/`--config` в пустой папке по-прежнему
   создаёт конфиг — это штатный путь мастера.
4. **CHANGELOG — относительные ссылки на страницы сайта в репозитории**
   (`docs/en/src/07%20Docker%20and%20CI/README.md`, `docs/en/src/06%20Plugins/README.md`):
   работают на GitHub без опубликованного сайта (Pages пока не включены) и в npm-пакете
   не нужны — `CHANGELOG.md` в него не входит.

## Risks / Trade-offs

- [Скрипты, грепающие `строка` в выводе `check`] → строка в `## Unreleased` с явным
  указанием смены формата; документация уже описывает `line`-формат после актуализации.
- [Повтор с C4 скрывает ошибку, вызванную именно отсутствием C4 у самостоятельной
  библиотеки, которая обязана подключать его сама] → такая библиотека всё равно
  сломается в диаграмме-потребителе при сборке; `check` проверяет синтаксис, а не
  политику инклюдов.
- [Время `check` на битой `.iuml` удваивается] → только на ошибочном пути.
- [`--list`/`--reset` вне проекта теперь код 1 вместо 0] → раньше это было тихой порчей
  каталога; новое поведение описано в спеке и changelog.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. `check`: `.iuml` с C4 и английский вывод

- [x] 1.1 Тест сначала (`test/check.test.mjs`): фикстура `c4-styles.iuml` (`skinparam` + `UpdateElementStyle("person", $bgColor="#000")`) → `✓`, код 0; ожидание `строка 3` → `line 3`; `неизвестное расширение` → `unsupported extension`; без аргументов — stdout содержит `usage: c4builder check`. Проверка: `npm run build && npx vitest run test/check.test.mjs` — новые ожидания красные на текущем коде.
- [x] 1.2 `src/cli/commands/check.ts` по design §1–2: для `.iuml` при ошибке движка повтор с обёрткой `!include <C4/C4_Dynamic>` + `!include <C4/C4_Deployment>` перед файлом, ошибка — от повтора; сообщения `line N`, `usage: …`, `unsupported extension (…)`; комментарий про повтор — почему (контекст C4 задаёт потребитель). Проверка: `npx vitest run test/check.test.mjs` зелёный, включая существующий кейс `bad.iuml` → `Error in function definition`; `node dist/index.js check template/src/styles.iuml` → `✓`, код 0.

## 2. Справочные команды без побочных эффектов

- [x] 2.1 Тест сначала (`test/cli-commands.test.mjs`): в пустом temp-каталоге `--docs` → код 0, каталог пуст; `--list` и `--reset` → код ≠ 0, stderr содержит `no .c4builder`, каталог пуст; в каталоге проекта (`new --name demo -y`, затем `cd demo`) `--list` → код 0 и печатает `projectName`. Проверка: новые кейсы красные на текущем коде.
- [x] 2.2 `src/cli/dispatch.ts` по design §3: `if (opts.docs) return cmdHelp();` до создания `Configstore`; для `--list`/`--reset` без файла `configPath` — сообщение в stderr и `process.exit(1)` до `Configstore`. Проверка: `npx vitest run test/cli-commands.test.mjs` зелёный; ручной прогон в `mktemp -d`: `node dist/index.js --docs; ls -A` — пусто.

## 3. CHANGELOG

- [x] 3.1 В `CHANGELOG.md` заменить `(see [Docker](#docker))` и `(see «Plugins»)` на относительные ссылки `docs/en/src/07%20Docker%20and%20CI/README.md` и `docs/en/src/06%20Plugins/README.md` (design §4). Проверка: `grep -n '](#\|see «' CHANGELOG.md` пусто; оба целевых файла существуют.

## 4. Актуализация

- [x] 4.1 Сайт RU/EN, страница «03 Диаграммы» / «03 Diagrams»: пример вывода `строка 4` → `line 4`, убрать абзац «`.iuml` с макросами C4 отдельно не проходит» (заменить: `.iuml` с макросами C4 проверяется в контексте C4-stdlib), в pre-commit-хук вернуть `'*.iuml'`; в EN убрать пояснения «`строка` means "line"» / «messages are printed in Russian». Страница «08 Агенты» / «08 Agents»: пример вывода и пояснение про `строка`. Страница «05 CLI и конфигурация» / «05 CLI and configuration»: у `--list`/`--reset` — «в каталоге проекта; вне проекта — ошибка». Проверка: `grep -rn 'строка [0-9N<]' docs/*/src` пусто; сборка docs/ru и docs/en → код 0; `npx vitest run test/docs-parity.test.mjs` зелёный.
- [x] 4.2 `skills/c4builder/SKILL.md` (шаг check: формат `✗ <file>: line <N>: <message>`, убрать пояснение про `строка` и совет не проверять `.iuml` отдельно) и `template/AGENTS.md` (формат ошибки, `.iuml` можно проверять напрямую). Проверка: `grep -rn 'строка' skills template/AGENTS.md` пусто; `npx vitest run test/skills.test.mjs` зелёный.
- [x] 4.3 `README.MD` строка 52: `"✗ file: line N: message"`. Проверка: `grep -n 'строка' README.MD` пусто.
- [x] 4.4 `CHANGELOG.md`, `## Unreleased`: `check` печатает `line N` и английские сообщения (смена формата вывода); `.iuml` с макросами C4 проходит `check`; `--docs` не создаёт файлов, `--list`/`--reset` вне проекта — ошибка без создания `.c4builder`. Проверка: ревью глазами.
- [x] 4.5 Полный прогон: `npm run build`, `npm test`, `npm run check`, `openspec validate cli-fixes --strict` — всё зелёное.

## specs

[Обзор](#C4-Builder)

- [cli-commands](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-fixes/specs/cli-commands/cli-commands)

## cli-commands

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Формат вывода проверки диаграмм
`c4builder check <file...>` SHALL печатать результат по каждому файлу в стабильном англоязычном формате: успешный файл — `✓ <file>`, ошибочный — `✗ <file>: line <N>: <message>` для `.puml` (номер строки — от начала файла, начиная с 1), `✗ <file>: <message>` для `.iuml` (позиция относится к обёртке, номер не печатается). Сообщения об использовании команды без аргументов и о неподдерживаемом расширении MUST быть на английском. Код возврата MUST быть 0, если все файлы прошли проверку, и 1 иначе.

#### Scenario: Ошибка в диаграмме
- **WHEN** выполняется `c4builder check bad.puml`, где в строке 3 синтаксическая ошибка
- **THEN** в stderr печатается `✗ bad.puml: line 3: <сообщение движка>`, процесс завершается с кодом 1

#### Scenario: Неподдерживаемое расширение
- **WHEN** выполняется `c4builder check notes.txt`
- **THEN** печатается сообщение на английском о неподдерживаемом расширении со списком `.puml`, `.iuml`, `.d2`, процесс завершается с кодом 1

#### Scenario: Без аргументов
- **WHEN** выполняется `c4builder check` без файлов
- **THEN** печатается строка использования на английском, процесс завершается с кодом 1

### Requirement: Проверка библиотек .iuml с макросами C4
`c4builder check` SHALL проверять файл `.iuml` в контексте, где подключена стандартная библиотека C4-PlantUML (все уровни: контекст, контейнеры, компоненты, динамические и deployment-диаграммы): корректная библиотека, вызывающая макросы C4 (`UpdateElementStyle`, `Person`, `System` и т. п.), MUST проходить проверку. Библиотека без макросов C4 MUST проверяться с тем же результатом, что и раньше, а синтаксическая ошибка в `.iuml` MUST по-прежнему приводить к коду 1.

#### Scenario: Стили на макросах C4
- **WHEN** выполняется `c4builder check styles.iuml`, где файл содержит только `skinparam` и вызовы `UpdateElementStyle(...)`
- **THEN** печатается `✓ styles.iuml`, процесс завершается с кодом 0

#### Scenario: Библиотека без C4
- **WHEN** проверяется `.iuml` только со `skinparam` или объявлениями `participant`
- **THEN** проверка проходит, как и до изменения

#### Scenario: Битая библиотека
- **WHEN** в `.iuml` незакрытый вызов макроса
- **THEN** печатается `✗ <file>: <сообщение движка>`, процесс завершается с кодом 1

### Requirement: Справочные команды не создают файлов
Команды `c4builder --docs`, `c4builder --list` и `c4builder --reset` MUST NOT создавать `.c4builder`, `.c4builder.cache` или иные файлы в текущем каталоге. `--docs` SHALL работать в любом каталоге и завершаться с кодом 0. `--list` и `--reset` в каталоге без файла конфигурации SHALL печатать сообщение, что проект (`.c4builder`) не найден, и завершаться с ненулевым кодом; в каталоге проекта их поведение не меняется.

#### Scenario: Справка в пустой папке
- **WHEN** в пустом каталоге выполняется `c4builder --docs`
- **THEN** справка по ключам печатается, процесс завершается с кодом 0, каталог остаётся пустым

#### Scenario: Просмотр конфига вне проекта
- **WHEN** в пустом каталоге выполняется `c4builder --list`
- **THEN** печатается сообщение, что `.c4builder` не найден, процесс завершается с ненулевым кодом, каталог остаётся пустым

#### Scenario: Сброс вне проекта
- **WHEN** в пустом каталоге выполняется `c4builder --reset`
- **THEN** печатается сообщение, что `.c4builder` не найден, процесс завершается с ненулевым кодом, файлы не создаются

## 2026-10-03-cli-english-messages

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="11" max="11"></progress> 11/11 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-english-messages/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-english-messages/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-english-messages/specs/specs)

## Why

CLI говорит на двух языках: `--help`, вопросы мастера, `--list` и часть предупреждений —
английские, а ошибки конфига, сборки, плагинов, JRE, лока и валидация мастера (~100 строк
кода, ~75 сообщений в 25 файлах `src/`) — русские. Смесь хуже любого из языков: англоязычный
пользователь получает ошибку, которую не прочтёт, а английская документация вынуждена
оговаривать «messages are printed in Russian for now». Вывод CLI разбирают агенты, хуки и
CI — им нужен один предсказуемый язык. Русской аудитории хватает русского сайта
документации. Change `cli-fixes` переводит только вывод `check` (контракт формата ошибок);
здесь — всё остальное.

## What Changes

- Все сообщения CLI для пользователя (stdout/stderr: ошибки, предупреждения, подсказки,
  прогресс, валидация ответов мастера, тексты исключений, доходящие до пользователя,
  заглушка «диаграмма не отрендерена» на странице сайта) — на английском, в стиле
  существующих английских сообщений и `--help`.
- Одна локаль, без i18n-фреймворка и без выбора языка: переводятся строковые литералы
  на месте.
- Комментарии в коде остаются на русском (правило репозитория) — меняются только
  строковые литералы.
- Тест против регресса: в строковых литералах `src/**/*.ts` нет кириллицы (комментарии
  не учитываются).
- Тесты, сверяющие русские тексты сообщений, переходят на английские.
- Сайт (EN-версия), скилл `c4builder` и `template/AGENTS.md` больше не оговаривают
  русский вывод.

## Capabilities

### New Capabilities
- (нет)

### Modified Capabilities
- `cli-commands`: новое требование — язык пользовательского вывода CLI английский;
  кириллица в строковых литералах исходников CLI запрещена тестом.

## Impact

- `src/**/*.ts` — ~25 файлов, только строковые литералы: `cli/dispatch.ts`,
  `cli/commands/{new,jre,list,help}.ts`, `cli/wizard/collect.ts`, `config/{schema,options}.ts`,
  `core/build.ts`, `core/scan/tree.ts`, `core/compose/markdown.ts`,
  `core/render/{diagrams,jre,d2renderer,pngraster}.ts`, `core/plugins/{load,hooks,tree,source}.ts`,
  `plugins/{openapi,openspec}/index.ts`, `util/{lock,http,archive,paths}.ts`.
- Тесты с русскими ожиданиями: `plugins-tree`, `plugins-source`, `plugins-load`,
  `plugin-openapi`, `plugin-openspec`, `llms`, `config`, `compose-h1`, `cli-commands`.
- Golden-эталоны не меняются, если заглушка не отрендеренной диаграммы в них не попадает
  (проверяется прогоном).
- **Зависимость:** реализуется после merge `cli-fixes` — тот меняет `check.ts`,
  `dispatch.ts` и тесты `check`; параллельная работа дала бы конфликты.
- Поведение для скриптов, которые парсят русские сообщения CLI, меняется (сообщения не
  были контрактом, кроме формата `check`, который уже переводит `cli-fixes`).
- Новых зависимостей нет: проверка литералов использует уже установленный `typescript`.

## design

[Обзор](#C4-Builder)

# Design

## Context

- Инвентарь (grep кириллицы вне комментариев по `src/**/*.ts`, на 4220c8d): ~100 строк
  кода, ~75 сообщений в 26 файлах. Больше всего: `core/render/jre.ts` (15 строк),
  `cli/wizard/collect.ts` (9), `core/render/diagrams.ts` (7), по 6 — `d2renderer.ts`,
  `plugins/source.ts`, `plugins/load.ts`, `cli/dispatch.ts`, `cli/commands/new.ts`,
  `cli/commands/jre.ts`; остальные — 1–5. Ложные срабатывания grep (комментарий после кода):
  `jre.ts:60`, `dispatch.ts:163`. `cli/commands/check.ts` (3 строки) переводит `cli-fixes`.
- Сообщения уходят к пользователю тремя путями: `console.log/error` (часто через `chalk`),
  `throw new Error(...)` (печатает CLI или build), строки-ответы валидаторов мастера
  (inquirer показывает их как есть) и zod-сообщения схемы конфига. Дефолтные сообщения zod
  и commander уже английские.
- Английские сообщения в коде уже есть и задают стиль: `unknown command: <x>`,
  `generating llms.txt`, вопросы мастера, `--help` — со строчной буквы, без точки в конце,
  символы `⚠`/`✗`/`✓` как маркеры.
- Тесты сверяют русские тексты в 9 файлах (`toThrow(/…/)`, `toContain`, `toMatch`). Русские
  имена страниц и папок в фикстурах (`Система А`, `Планы`, `Локализация`) — пользовательский
  контент, а не сообщения CLI; их не трогаем.
- Спеки в `openspec/specs/` не фиксируют русские тексты сообщений дословно (описывают смысл),
  поэтому существующие требования не меняются; добавляется одно требование в `cli-commands`.
- `typescript` 5.9.3 уже в devDependencies.

## Goals / Non-Goals

**Goals:**
- Весь пользовательский вывод CLI и служебные тексты в выходах сборки — на английском.
- Регресс (новая русская строка в литерале) ловится обычным `npm test`.

**Non-Goals:**
- i18n: каталог сообщений, выбор языка по локали или флагу.
- Перевод комментариев в коде (они остаются русскими по правилу репо).
- Перевод тестовых сообщений (`expect(x, 'сообщение')`) и фикстур с русским контентом.
- Вывод `check` — его переводит `cli-fixes`.
- Переписывание сообщений сверх перевода: смысл, подсказки и подставляемые значения те же.

## Decisions

1. **Перевод литералов на месте, без каталога сообщений.** ~75 сообщений, одна локаль —
   каталог или ключи (`t('lock.held')`) добавили бы индирекцию без пользы. *Альтернатива:*
   i18n с RU/EN по `LANG` — удвоение поддержки, а вывод разбирают агенты и CI, которым
   нужен один язык.
2. **Стиль — как у существующих английских сообщений.** Со строчной буквы, без точки в
   конце однострочных сообщений; многострочные подсказки (JRE, отсутствующие пакеты) —
   полными предложениями. Идентификаторы и команды — в обратных кавычках, как в `--help`;
   «ёлочки» → двойные кавычки. Подставляемые значения и порядок частей сообщения не
   меняются — меняется только язык.
3. **Проверка против регресса — тест на AST через установленный `typescript`.**
   `test/cli-language.test.mjs`: рекурсивно все `src/**/*.ts`, `ts.createSourceFile`, обход
   узлов; для `StringLiteral`, `NoSubstitutionTemplateLiteral`, `TemplateHead/Middle/Tail`
   проверяется `.text` на `/[А-Яа-яЁё]/`; падение перечисляет `файл:строка: литерал`.
   Комментарии не являются узлами-литералами — ложных срабатываний на них нет; регэкспы
   (`RegularExpressionLiteral`) не проверяются (не вывод). *Альтернативы:* grep с вырезанием
   комментариев регэкспом — ломается на `//` внутри строк и URL; линт-правило biome для
   языка строк отсутствует. Allowlist не заводим: в `src/` нет функциональных
   кириллических литералов; появится — добавим явный список с причиной.
4. **Порядок: сначала красный тест, потом перевод по областям.** Тест из решения 3 сразу
   даёт полный и точный инвентарь (лучше grep), задачи закрывают его по областям, тест
   зеленеет в конце. Связанные тесты с русскими ожиданиями правятся в той же задаче, что и
   соответствующий код.
5. **Реализация после merge `cli-fixes`.** Он меняет `check.ts`, `dispatch.ts` и тесты
   `check`; здесь `dispatch.ts` тоже меняется — последовательность исключает конфликт и
   двойной перевод.

## Risks / Trade-offs

- [Скрипты пользователей, грепающие русские сообщения] → сообщения не были контрактом
  (кроме формата `check`, который уже меняет `cli-fixes`); строка в CHANGELOG предупреждает.
- [Параллельные change'и (`bpmn-diagrams`, `offline-site-assets`, `node-22`) добавят русские
  литералы] → после merge этого change'а тест покраснеет на их ветках; тот, кто вливает
  позже, переводит свои строки. Правило «Актуализация» и `CLAUDE.md` дополняются
  упоминанием языка вывода.
- [Golden-эталоны] → тексты сообщений в эталоны не попадают; заглушка не отрендеренной
  диаграммы — только при ошибке рендера, в эталонах её нет. Подтверждается прогоном
  `test:golden` без изменений эталонов.
- [Перевод исказит смысл подсказки (JRE, TLS, лок)] → ревью диффа сообщений по одному
  файлу на задачу; подставляемые значения не меняются.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 1. Подготовка и тест против регресса

- [x] 1.1 Убедиться, что `cli-fixes` влит в базу ветки (`git log --oneline | grep -i cli-fixes` или переведённый вывод `check` в `src/cli/commands/check.ts`); иначе остановиться и сообщить. `npm run build`. Проверка: `node dist/index.js check /nonexistent.txt` печатает английское сообщение
- [x] 1.2 Добавить `test/cli-language.test.mjs` по design §3: обход `src/**/*.ts`, AST через `typescript`, литералы `StringLiteral`/`NoSubstitutionTemplateLiteral`/`TemplateHead|Middle|Tail` без кириллицы, сообщение — список `файл:строка: литерал`. Проверка: тест красный на текущем коде и перечисляет литералы из инвентаря design (в том числе `core/render/jre.ts`, `cli/wizard/collect.ts`), но НЕ комментарии `jre.ts:60` и `dispatch.ts:163`

## 2. Перевод: CLI и конфиг

- [x] 2.1 `cli/dispatch.ts`, `cli/commands/{new,jre,list,help}.ts` (в `help.ts` — «(по-русски)» → «(in Russian)»), `cli/wizard/collect.ts` (сообщения валидаторов), `config/schema.ts`, `config/options.ts` («(корень)» → «(root)»); тесты с русскими ожиданиями этих сообщений (`cli-commands`, `config`) — на английские. Проверка: `npx vitest run test/cli-commands.test.mjs test/config.test.mjs` зелёный; в `cli-language` больше нет литералов из этих файлов

## 3. Перевод: ядро сборки и рендер

- [x] 3.1 `core/build.ts`, `core/scan/tree.ts`, `core/compose/markdown.ts`; тесты (`llms` — предупреждение `generateLLMS`/`generateWEB`, `compose-h1`) — на английские ожидания. Проверка: `npx vitest run test/llms.test.mjs test/compose-h1.test.mjs` зелёный
- [x] 3.2 `core/render/{diagrams,jre,d2renderer,pngraster}.ts`, включая заглушку «диаграмма не отрендерена»; тесты `plugin-openspec` (текст заглушки), `jre`, `pngraster` — на английские ожидания. Проверка: `npx vitest run test/plugin-openspec.test.mjs test/jre.test.mjs test/pngraster.test.mjs` зелёный

## 4. Перевод: плагины и утилиты

- [x] 4.1 `core/plugins/{load,hooks,tree,source}.ts`, `plugins/{openapi,openspec}/index.ts`; тесты `plugins-load`, `plugins-tree`, `plugins-source`, `plugin-openapi`, `plugin-openspec` — на английские ожидания. Проверка: эти тесты зелёные
- [x] 4.2 `util/{lock,http,archive,paths}.ts`; тест `lock` при наличии русских ожиданий — на английские. Проверка: `npx vitest run test/lock.test.mjs` зелёный; `npx vitest run test/cli-language.test.mjs` зелёный (литералов с кириллицей в `src/` не осталось)

## 5. Актуализация

- [x] 5.1 Сайт: в `docs/en/src` убрать оговорки о русском выводе (например `03 Diagrams` — «messages are printed in Russian for now»), в RU и EN поправить цитаты сообщений CLI, если они есть (`grep -rnP '[А-Яа-яЁё]' docs/en/src` и поиск процитированных сообщений в `docs/ru/src`). Проверка: `npx vitest run test/docs-parity.test.mjs` зелёный; сборка `cd docs/ru && node ../../dist/index.js` и `docs/en` — код 0
- [x] 5.2 `skills/c4builder/**` и `template/AGENTS.md`: убрать оговорки о русских сообщениях CLI, если остались после `cli-fixes`. Проверка: `grep -rniE 'russian|строка' skills template/AGENTS.md` — только осознанные упоминания; `npx vitest run test/skills.test.mjs` зелёный
- [x] 5.3 `CLAUDE.md`: в «Правила» — пользовательский вывод CLI только на английском (тест `cli-language`), комментарии — по-прежнему на русском. Строка в `## Unreleased` `CHANGELOG.md`: весь вывод CLI на английском, скриптам, разбиравшим русские сообщения, — обновиться. Проверка: ревью глазами

## 6. Интеграция

- [x] 6.1 `npm run build`, `npm test` (golden — эталоны без изменений), `npm run check`, `openspec validate cli-english-messages --strict` — всё зелёное

## specs

[Обзор](#C4-Builder)

- [cli-commands](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-cli-english-messages/specs/cli-commands/cli-commands)

## cli-commands

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Язык пользовательского вывода CLI
Все сообщения, которые CLI выводит пользователю (stdout и stderr: ошибки, предупреждения, подсказки, прогресс сборки, вывод `--docs` и `--list`, сообщения валидации мастера настройки, тексты исключений, доходящие до пользователя), а также служебные тексты, которые сборка вставляет в выходы (заглушка вместо не отрендеренной диаграммы), SHALL быть на английском языке. Выбора языка вывода MUST NOT быть. Строковые литералы исходного кода CLI MUST NOT содержать кириллицу; комментарии в коде этим требованием не ограничены. Соблюдение MUST проверяться автоматическим тестом.

#### Scenario: Ошибка конфигурации на английском
- **WHEN** сборка запускается с `.c4builder`, где у ключа значение не того типа
- **THEN** сообщение об ошибке, перечисляющее невалидные ключи, напечатано на английском, процесс завершается с ненулевым кодом

#### Scenario: Предупреждение сборки на английском
- **WHEN** в `.c4builder` `generateLLMS: true`, а `generateWEB: false`
- **THEN** предупреждение о том, что `generateLLMS` требует `generateWEB`, напечатано на английском

#### Scenario: Валидация ответа мастера на английском
- **WHEN** в мастере `c4builder --config` пользователь оставляет имя проекта пустым
- **THEN** подсказка о недопустимом ответе выведена на английском

#### Scenario: Кириллица в строковом литерале
- **WHEN** в строковый литерал (обычный или шаблонный) в `src/` добавлен текст на кириллице
- **THEN** автоматический тест падает с сообщением, называющим файл и строку

#### Scenario: Кириллица в комментарии
- **WHEN** в `src/` есть комментарий на русском
- **THEN** тест на язык литералов не падает

## 2026-10-03-agent-skills

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-10-03 · **Tasks:** <progress value="17" max="17"></progress> 17/17 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/specs/specs)

## Why

Агенты (Claude Code, Codex, Cursor) уже пишут C4-модели, но не знают устройства проекта
c4builder, конвенций C4-PlantUML и главного: цикла правка → `c4builder check` → сборка,
который даёт агенту быструю проверку без человека. Единственный скилл сейчас — корпоративный
`c4builder-setup` в отдельном маркетплейсе: он привязан к внутреннему Artifactory и
версионируется отдельно от продукта. Remotion показал рабочую модель: скиллы лежат в
репозитории продукта, ставятся одной командой для любого агента и предлагаются при создании
проекта. Это и есть адаптация инструмента под агентскую разработку, а не только документация.

## What Changes

- **Каталог `skills/` в репозитории** в формате Agent Skills (`SKILL.md` с frontmatter),
  устанавливается командой `npx skills add AlfaCapital-Tech/C4-Builder/skills` в любой
  поддерживаемый агент. В npm-пакет скиллы не входят.
- **Первый набор из двух скиллов** (английский текст, без внутренних хостов):
  - `c4builder` — общий: структура проекта и `.c4builder`, конвенции C4-PlantUML
    (stdlib-инклюды, `.iuml`, кириллица), цикл правка → `check` → `--site -w`, D2,
    плагины `openspec`/`openapi`, `llms.txt`;
  - `c4builder-setup` — установка и диагностика: npm/Docker, каналы `latest`/`rc`, Java
    или managed JRE, функциональный smoke на шаблонном проекте.
- **Шаблон `new` содержит `AGENTS.md`**: как собирать и проверять проект, команда установки
  скиллов. Файл лежит вне `src/` шаблона и в сайт не попадает.
- **CLI понимает позиционные `new` и `config`** (`c4builder new`, `c4builder config`) —
  форма, которой учат README, шаблон и скиллы; сейчас она молча запускает сборку.
  Неизвестный позиционный аргумент даёт ошибку и код 1 вместо сборки.
- **CI проверяет скиллы**: валидный frontmatter (`name` совпадает с именем папки, есть
  `description`) и упомянутые в скиллах команды/флаги CLI существуют.
- Вне скоупа: скилл сверки C4-модели с кодом (обобщение внутренних `arch-review`/
  `arch-actualize`) — следующий change. Перевод корпоративного плагина `c4builder` на
  публичные скиллы (останется тонкая обёртка над Artifactory) — отдельно, в репозитории
  маркетплейса.

## Capabilities

### New Capabilities
- `agent-skills`: состав и формат поставляемых скиллов, способ установки, проверка в CI.
- `cli-commands`: позиционные подкоманды CLI (`check`, `jre`, `site`, `new`, `config`) и
  ошибка на неизвестную.

### Modified Capabilities
- `project-template`: шаблон содержит `AGENTS.md` с инструкциями для агента.

## Impact

- Новые `skills/c4builder/SKILL.md`, `skills/c4builder-setup/SKILL.md` (+ references при
  необходимости).
- `src/cli/dispatch.ts` — позиционные `new`/`config`, ошибка на неизвестную подкоманду.
- `template/AGENTS.md`; golden-эталоны не меняются (файл вне `src/`).
- `.github/workflows/ci.yml` или vitest — проверка скиллов.
- Документация: страница «Работа с агентами» (сайт из `docs-site`; до его реализации —
  README) и changelog.
- Связь с `llms-txt`: общий скилл упоминает `llms.txt`. Если `llms-txt` ещё не
  реализован, упоминание добавляется последней задачей.
- Новых npm-зависимостей нет.

## design

[Обзор](#C4-Builder)

# Design

## Context

Мотивация — см. proposal.md. Факты, которые определяют подход:

- **Формат и установка.** Спека Agent Skills (agentskills.io/specification): скилл — каталог с
  `SKILL.md` (YAML frontmatter + markdown), обязательные `name` (1–64, `a-z0-9-`, без
  ведущего/хвостового/двойного дефиса, равен имени каталога) и `description` (1–1024).
  Рекомендации: тело до ~500 строк / 5000 токенов, детали — в `references/` на один уровень
  вложенности (прогрессивная загрузка). CLI `npx skills add <owner>/<repo>`
  (github.com/vercel-labs/skills) сканирует корень, `skills/` и агентские пути
  (`.claude/skills/` и др.) на глубину до трёх уровней, `--skill <name>` ставит один скилл,
  кладёт в `.claude/skills/` (проект) или `~/.claude/skills/` (`-g`) и аналоги для 75+ агентов.
  Корень репозитория уже несёт dev-скиллы OpenSpec в `.claude/skills/` (генерирует
  `openspec update`) — `npx skills add <owner>/<repo>` предложил бы и их, поэтому команда
  установки указывает подкаталог: `npx skills add AlfaCapital-Tech/C4-Builder/skills`
  (shorthand `<owner>/<repo>/<subpath>`, поиск только внутри `skills/`; проверено `--list`).
- **Remotion** (`packages/skills/skills/*`): общий скилл `remotion-best-practices` —
  маршрутизатор («задача X → загрузи скилл Y»), остальные — узкие. Для двух скиллов
  маршрутизатор избыточен — берём только идею «общий скилл + узкий».
- **CLI** (`src/cli/dispatch.ts`): флаги commander'а (`--new`, `--name`, `-y`, `--config`,
  `--site`, `-w`, `-o`, `-p`, `--list`, `--docs`, `--system-fonts`, `--force`, …) и
  позиционные подкоманды, разбираемые вручную: `check`, `jre`, `site`. Позиционных `new` и
  `config` **нет** — `c4builder new` молча уходит в сборку, хотя README и шаблон учат именно
  этой форме. Корень дефекта — `allowExcessArguments()`: любой неизвестный позиционный
  аргумент глотается и запускает сборку. Чиним в этом change'е (решение 7): скиллы
  учат `c4builder new`.
- **Шаблон.** `c4builder --new` копирует `template/` целиком в каталог проекта
  (`fsextra.copy`), сайт строится только из `src/`. Golden-фикстуры копируют лишь
  `template/src` (`test/helpers.mjs`). `package.json` `files` включает `template/` →
  файл в корне шаблона попадает в пакет и в новый проект, но не в выходы и не в golden.
- **Корпоративный `c4builder-setup`** (маркетплейс): шаги Node → версия/канал → установка
  → java/managed JRE → smoke на шаблоне; привязан к `--registry` внутреннего Artifactory.
- В зависимостях нет YAML-парсера; плагин `openspec` уже читает `.openspec.yaml` построчно.

## Goals / Non-Goals

**Goals:**
- Два скилла, которые ставятся одной командой в любой агент и не расходятся с CLI.
- Дрейф «скилл ↔ CLI» и утечка внутренних хостов ловятся обычным `npm test` в CI.
- Новый проект сразу объясняет агенту, как собирать и проверять диаграммы.

**Non-Goals:**
- Скилл сверки C4-модели с кодом, маршрутизатор скиллов, `scripts/` в скиллах.
- Команда CLI для установки скиллов (`c4builder skills …`) — `npx skills` уже это делает.
- Версионирование скиллов отдельно от репозитория (скиллы берутся с default-ветки).
- Позиционное имя проекта (`c4builder new demo`) — имя по-прежнему через `--name`.

## Decisions

1. **`skills/<name>/SKILL.md` в корне репозитория, не в npm-пакете.** Стандартный путь,
   который `npx skills` находит без настроек. *Альтернатива:* класть в пакет и ставить из
   `node_modules` — привязало бы скиллы к версии CLI, но требует своей команды установки
   и меняет `files`-whitelist (`dev-toolchain`). Цена решения: скиллы с `master` могут
   опережать установленный stable CLI → в скиллах описываем только то, что есть в
   `latest`, новинки из `rc` помечаем «since vX.Y».
2. **Структура скилла `c4builder`:** `SKILL.md` (≤ ~200 строк: когда применять, раскладка
   проекта, цикл правка → `check` → `--site -w`/сборка, частые ошибки) + `references/`:
   `config.md` (ключи `.c4builder` по `c4builder --docs`), `diagrams.md` (C4-PlantUML
   stdlib, `.iuml`, кириллица, D2), `plugins.md` (`openspec`, `openapi`). Ссылки из
   `SKILL.md` — с условием загрузки («read when editing `.c4builder`»). *Альтернатива:* один
   длинный файл — грузит весь контекст при каждой активации.
3. **`c4builder-setup` — один `SKILL.md`** (шаги короткие, references не нужны): Node →
   канал (`latest`/`rc`, без аргумента — `latest`; даунгрейд только с подтверждения) →
   `npm i -g @alfacapital-tech/c4builder@<tag>` или `docker run … ghcr.io/alfacapital-tech/c4builder`
   → java/`c4builder jre install` → smoke `c4builder --new --name smoke -y` + сборка во
   временном каталоге. Корпоративный скилл в маркетплейсе потом сводится к «задай
   `--registry` и выполни публичный `c4builder-setup`» — вне этого change'а.
4. **Проверка — один vitest-файл `test/skills.test.mjs`** (~40 строк), а не отдельный
   workflow: идёт в существующем `npm test` на CI. Входы: `skills/*/SKILL.md` и
   `template/AGENTS.md`. Проверки:
   - frontmatter — построчный разбор между `---` (как `.openspec.yaml` в плагине), правила
     `name`/`description` по спеке;
   - флаги/подкоманды — из строк кода, начинающихся с `c4builder ` (inline-код и
     fenced-блоки), берутся токены `-x`/`--xx` и токен сразу после `c4builder`, если это
     не флаг (значения опций вроде `--name smoke` и файлы после `check` не трогаем);
     флаги сверяются с выводом `node dist/index.js --help`, подкоманда — со списком
     `check|jre|site|new|config`;
   - денайлист внутренних хостов — регэксп `alfacapital\.ru` по всем входам.
   *Альтернатива:* `skills-ref validate` из agentskills — внешняя Python-зависимость ради
   десятка строк проверок.
5. **Один `template/AGENTS.md`, без `CLAUDE.md`.** AGENTS.md читают Codex, Cursor и др.;
   Claude Code с v2.1.277 (2026-09) читает его, когда в пути нет `CLAUDE.md`. *Альтернатива:*
   `CLAUDE.md` с `@AGENTS.md` — второй файл ради старых версий Claude Code; добавим, если
   пользователи пожалуются. Файл в корне шаблона: копируется `--new`, в пакет попадает,
   в сайт и golden — нет. Явная проверка: `new -y` во временном каталоге → `AGENTS.md`
   есть, в собранном `docs/` его нет (дешёвый тест рядом со `skills.test.mjs`, сборка без
   golden-сравнения не нужна — достаточно факта наличия файла и отсутствия в выходах).
6. **Язык — английский** в скиллах и `AGENTS.md`: публичный продукт, агенты одинаково
   работают с обоими, а английский — язык CLI-вывода и `--help`.

7. **Позиционные `new` и `config` в CLI; неизвестный позиционный аргумент — ошибка.** В
   `dispatch.ts` рядом с `site`: `new` → `opts.new`, `config` → `opts.config` (дальше
   существующий путь флагов, комбинации `c4builder new --name demo -y` работают как с
   `--new`). Первый позиционный аргумент вне `check|jre|site|new|config` → сообщение
   «unknown command: <x>» со списком команд и код 1 — это и есть корень дефекта: опечатка
   (`c4builder nwe`) больше не превращается в сборку. *Альтернатива:* перевести CLI на
   commander `.command()` — правильнее структурно, но меняет разбор всех флагов и `--help`;
   для двух алиасов несоразмерно.

## Risks / Trade-offs

- [Скиллы с `master` опережают stable CLI] → описывать только `latest`; новинки — с
  пометкой версии; тест сверяет с текущим `dist/`, т.е. с `master`.
- [Эвристика извлечения флагов пропустит команду в прозе без `c4builder` в начале] →
  конвенция: команды в скиллах всегда в code-span/fenced-блоке и начинаются с `c4builder`.
- [Формат `npx skills` поменяется] → путь `skills/<name>/SKILL.md` — общий для спеки
  Agent Skills, не специфика одного CLI; ручная проверка установки — задача перед мержем.
- [Денайлист ловит только известный домен] → это страховка от самой вероятной утечки
  (копипаста из корпоративного скилла), а не полный DLP.

## Migration Plan

Чисто аддитивно: новые `skills/`, `template/AGENTS.md`, тест. Существующие проекты не
затронуты (`AGENTS.md` появляется только в новых). Откат — удаление файлов.

## tasks

[Обзор](#C4-Builder)

# Tasks

## 0. CLI: позиционные `new` и `config`

- [x] 0.1 `src/cli/dispatch.ts` по design §7: `new` → `opts.new`, `config` → `opts.config`; первый позиционный аргумент вне `check|jre|site|new|config` → `unknown command: <x>` со списком команд в stderr, код 1, без сборки и без промптов. Проверка: тест `test/cli-commands.test.mjs` (spawn `node dist/index.js`) — `new --name demo -y` в temp-каталоге создаёт проект как `--new`; `nwe` → код 1 и сообщение; `check`/`jre info`/`site` не затронуты (существующие тесты зелёные)
- [x] 0.2 README: строки 57/125 (`c4builder new`, `c4builder config`) теперь корректны — сверить, добавить `new`/`config` в описание команд; строка changelog `## Unreleased`. Проверка: ревью глазами

## 1. Скилл `c4builder-setup` и проверка скиллов

- [x] 1.1 Подготовить worktree: `npm ci && npm run build`; проверка — `node dist/index.js --help` печатает список опций
- [x] 1.2 Написать `skills/c4builder-setup/SKILL.md` на английском по design §3 (Node ≥ 20.19 → канал `latest`/`rc`, даунгрейд только с подтверждения → `npm i -g @alfacapital-tech/c4builder@<tag>` или Docker-образ `ghcr.io/alfacapital-tech/c4builder` → java / `c4builder jre install`, `c4builder jre info` → smoke `c4builder --new --name smoke -y` + `c4builder` во временном каталоге). Без внутренних хостов и `--registry`; проверка — файл существует, frontmatter `name: c4builder-setup`, описание говорит «что и когда»
- [x] 1.3 Добавить `test/skills.test.mjs` по design §4: разбор frontmatter `skills/*/SKILL.md` (правила `name`/`description` из спеки), извлечение флагов и подкоманды из строк `c4builder …` и сверка с `node dist/index.js --help` и списком `check|jre|site|new|config`, денайлист `alfacapital\.ru`; сообщения об ошибке называют файл и найденное значение. Проверка — `npx vitest run test/skills.test.mjs` зелёный; временная порча (`name: c4-builder-setup`, команда `c4builder serve`, адрес `x.alfacapital.ru`) даёт красный тест с понятным сообщением, после отката — снова зелёный
- [x] 1.4 README: раздел «Agent skills» (что это, `npx skills add AlfaCapital-Tech/C4-Builder/skills`, `--skill <name>`, список скиллов) и строка в changelog `## Unreleased` (создать секцию над `## v0.4.0`; если change `docs-site` уже вмержен — в `CHANGELOG.md`); проверка — команды раздела совпадают с командами в `SKILL.md` (ревью глазами)

## 2. Общий скилл `c4builder`

- [x] 2.1 Написать `skills/c4builder/SKILL.md` (≤ ~200 строк, английский) по design §2: когда применять, раскладка проекта (`.c4builder`, `src/`, выходы), цикл правка → `c4builder check <file...>` → `c4builder --site -w` / `c4builder`, разбор ошибки `file: line N`, частые ошибки; ссылки на references с условием загрузки. Проверка — `test/skills.test.mjs` зелёный
- [x] 2.2 Написать `skills/c4builder/references/config.md` (ключи `.c4builder` по `node dist/index.js --docs` и `src/config/schema.ts`, `plugins`), `references/diagrams.md` (C4-PlantUML stdlib `<C4/...>`, общий `.iuml`, кириллица, D2, офлайн-рендер, `useSystemFonts`), `references/plugins.md` (`openspec`, `openapi` — опции из README «Plugins»). Проверка — каждый ключ/опция, упомянутые в references, есть в `src/config/schema.ts` или схеме плагина (сверка grep'ом), тест зелёный
- [x] 2.3 Расширить `test/skills.test.mjs`: входы — также `skills/*/references/*.md`; ожидаемый набор скиллов ровно `c4builder`, `c4builder-setup`. Проверка — тест зелёный; удаление одного каталога скилла даёт красный тест
- [x] 2.4 Дополнить раздел README «Agent skills» описанием `c4builder` и строку changelog; проверка — ревью глазами

## 3. `AGENTS.md` в шаблоне

- [x] 3.1 Написать `template/AGENTS.md` (английский, ~40 строк): `c4builder` (сборка), `c4builder check <file...>`, `c4builder --site -w`, исходники в `src/`, конвенции (stdlib `<C4/...>`, общий `styles.iuml`, офлайн), `npx skills add AlfaCapital-Tech/C4-Builder/skills`. Проверка — файл есть
- [x] 3.2 Добавить `template/AGENTS.md` во входы `test/skills.test.mjs` (флаги, подкоманды, денайлист). Проверка — тест зелёный
- [x] 3.3 Тест на шаблон (в `test/skills.test.mjs` или рядом): `node dist/index.js --new --name demo -y` во временном каталоге → `demo/AGENTS.md` существует; после сборки в `demo` (managed JRE, как в golden) в выходах нет `AGENTS.md`. Проверка — тест зелёный; `npm run test:golden` без изменений эталонов
- [x] 3.4 README: упомянуть `AGENTS.md` в описании `--new` и строку changelog; проверка — ревью глазами

## 4. Интеграция

- [x] 4.1 `npm test` и `npm run check` зелёные; `npm pack --dry-run` не содержит `skills/` и содержит `template/AGENTS.md`
- [x] 4.2 Ручная проверка установки (нужна сеть): в пустом каталоге `npx skills add <путь к worktree>` (после мержа — `AlfaCapital-Tech/C4-Builder/skills`) находит оба скилла и ставит их в `.claude/skills/`; при отсутствии сети — отметить задачу как ожидающую мейнтейнера в отчёте
- [x] 4.3 Зависит от change'а `llms-txt`: после его реализации добавить в `skills/c4builder/SKILL.md` (и `references/config.md`) упоминание `llms.txt`/`llms-full.txt` как точки входа для чтения архитектуры агентом; проверка — `test/skills.test.mjs` зелёный, ключ конфига совпадает с реализованным

## specs

[Обзор](#C4-Builder)

- [agent-skills](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/specs/agent-skills/agent-skills)
- [cli-commands](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/specs/cli-commands/cli-commands)
- [project-template](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-10-03-agent-skills/specs/project-template/project-template)

## agent-skills

[Обзор](#C4-Builder)

# Spec Delta

## Purpose

Скиллы для coding-агентов (Claude Code, Codex, Cursor и др.), поставляемые вместе с c4builder: их состав, формат, способ установки и автоматическая проверка на соответствие реальному CLI.

## ADDED Requirements

### Requirement: Скиллы поставляются из репозитория в формате Agent Skills
Репозиторий SHALL содержать скиллы в каталоге `skills/<name>/SKILL.md` в формате Agent Skills, устанавливаемые командой `npx skills add AlfaCapital-Tech/C4-Builder/skills` (весь набор) или с `--skill <name>` (один скилл). Каталог `skills/` MUST NOT попадать в публикуемый npm-пакет.

#### Scenario: Скиллы находятся в стандартном месте
- **WHEN** просматривается дерево репозитория
- **THEN** каждый поставляемый скилл лежит в `skills/<name>/SKILL.md`, где `<name>` — имя скилла

#### Scenario: Скиллы не входят в npm-пакет
- **WHEN** выполняется `npm pack --dry-run`
- **THEN** в списке файлов пакета нет путей `skills/`

### Requirement: Состав набора скиллов
Набор SHALL включать два скилла:
- `c4builder` — работа с проектом c4builder: структура проекта и `.c4builder`, конвенции C4-PlantUML (stdlib-инклюды `<C4/...>`, общие `.iuml`, кириллица, офлайн-рендер), цикл «правка → `c4builder check` → сборка / `c4builder --site -w`», D2, встроенные плагины `openspec` и `openapi`;
- `c4builder-setup` — установка и диагностика: npm (каналы `latest` и `rc`) или Docker-образ, Node.js версии из `engines` в `package.json`, системная java или managed JRE (`c4builder jre install` / `jre info`), функциональная проверка сборкой шаблонного проекта.

Тексты скиллов MUST быть на английском языке.

#### Scenario: Общий скилл описывает цикл проверки
- **WHEN** агент загружает скилл `c4builder`
- **THEN** скилл предписывает после правки `.puml`/`.iuml`/`.d2` запускать `c4builder check <file...>` и исправлять ошибки по коду возврата и сообщению `file: line N`

#### Scenario: Скилл установки проверяет работоспособность, а не только версию
- **WHEN** агент выполняет скилл `c4builder-setup`
- **THEN** скилл завершается созданием проекта `c4builder --new --name <name> -y` во временном каталоге и его сборкой, а не только проверкой `c4builder --version`

### Requirement: Метаданные скилла валидны
Frontmatter каждого `SKILL.md` MUST содержать `name` и `description`. `name` MUST совпадать с именем каталога скилла, иметь длину 1–64 символа, состоять из `a-z`, `0-9` и `-`, не начинаться и не заканчиваться дефисом и не содержать `--`. `description` MUST быть непустым, не длиннее 1024 символов и описывать, что делает скилл и когда его применять. Проверка MUST выполняться автоматическими тестами на каждом прогоне CI.

#### Scenario: Имя скилла расходится с каталогом
- **WHEN** в `skills/c4builder/SKILL.md` указано `name: c4-builder`
- **THEN** тесты падают с сообщением, называющим файл и ожидаемое имя

#### Scenario: Пустое описание
- **WHEN** у скилла нет `description` или он пустой
- **THEN** тесты падают с сообщением, называющим файл

### Requirement: Скиллы ссылаются только на существующие команды CLI
Каждый флаг (`--x`, `-x`) и каждая подкоманда, упомянутые в командах `c4builder …` внутри скиллов и `template/AGENTS.md`, MUST существовать в CLI текущей версии: флаги — в выводе `c4builder --help`, подкоманды — в списке поддерживаемых позиционных подкоманд (`check`, `jre`, `site`, `new`, `config`). Проверка MUST выполняться автоматическими тестами против собранного `dist/`.

#### Scenario: Скилл упоминает несуществующий флаг
- **WHEN** в скилле есть команда `c4builder --serve`, а флага `--serve` в CLI нет
- **THEN** тесты падают с сообщением, называющим файл и неизвестный флаг

#### Scenario: Скилл упоминает неподдерживаемую подкоманду
- **WHEN** в скилле есть команда `c4builder serve`, а позиционной подкоманды `serve` в CLI нет
- **THEN** тесты падают с сообщением, называющим файл и подкоманду

### Requirement: Скиллы не содержат внутренней инфраструктуры
Скиллы и `template/AGENTS.md` MUST NOT содержать адреса внутренних хостов и приватных реестров организации; установка MUST описываться только через публичные источники (npm registry, GHCR). Проверка MUST выполняться автоматическими тестами.

#### Scenario: Внутренний хост в скилле
- **WHEN** в тексте скилла встречается адрес в домене `alfacapital.ru`
- **THEN** тесты падают с сообщением, называющим файл и найденный адрес

## cli-commands

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Позиционные подкоманды CLI
CLI SHALL принимать позиционные подкоманды `check`, `jre`, `site`, `new` и `config`. `c4builder new` MUST вести себя так же, как `c4builder --new`, а `c4builder config` — как `c4builder --config`, включая сочетание с остальными флагами (`--name`, `-y`). Первый позиционный аргумент, не входящий в этот список, MUST приводить к сообщению об неизвестной команде со списком поддерживаемых и ненулевому коду возврата, без запуска сборки и без интерактивных вопросов.

#### Scenario: Позиционная команда создания проекта
- **WHEN** в пустом каталоге выполняется `c4builder new --name demo -y`
- **THEN** проект `demo` создаётся так же, как командой `c4builder --new --name demo -y`, процесс завершается с кодом 0

#### Scenario: Позиционная команда настройки
- **WHEN** в каталоге проекта выполняется `c4builder config`
- **THEN** запускается мастер настройки, как при `c4builder --config`

#### Scenario: Опечатка в команде
- **WHEN** выполняется `c4builder nwe`
- **THEN** печатается сообщение о неизвестной команде `nwe` со списком поддерживаемых, процесс завершается с ненулевым кодом, сборка не запускается

## project-template

[Обзор](#C4-Builder)

# Spec Delta

## ADDED Requirements

### Requirement: Шаблон содержит инструкции для агента
Проект, созданный `c4builder --new`, SHALL содержать в корне файл `AGENTS.md` на английском языке, который описывает: сборку (`c4builder`), проверку отдельных диаграмм (`c4builder check <file...>`), живой просмотр (`c4builder --site -w`), расположение исходников (`src/`) и конвенции диаграмм (stdlib-инклюды `<C4/...>`, общий `.iuml`, офлайн-рендер), а также команду установки скиллов `npx skills add AlfaCapital-Tech/C4-Builder/skills`. `AGENTS.md` MUST NOT попадать в выходы сборки (сайт, markdown, complete-markdown).

#### Scenario: AGENTS.md в новом проекте
- **WHEN** проект создан командой `c4builder --new --name demo -y`
- **THEN** в каталоге `demo/` есть `AGENTS.md` с командами `c4builder`, `c4builder check` и `npx skills add AlfaCapital-Tech/C4-Builder/skills`

#### Scenario: AGENTS.md не попадает в выходы
- **WHEN** новый проект собран командой `c4builder`
- **THEN** в каталоге выходов нет файла `AGENTS.md`, а сгенерированные страницы не содержат его текста

## 2026-07-24-nimbus-font-system-flag

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-24 · **Tasks:** <progress value="12" max="12"></progress> 12/12 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-24-nimbus-font-system-flag/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-24-nimbus-font-system-flag/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-24-nimbus-font-system-flag/specs/specs)

# Смена вендорного шрифта на Nimbus Sans + опция системных шрифтов

## Why

Обратная связь от пользователей: после пина вендорного Liberation Sans (клон Arial)
внешний вид диаграмм изменился — раньше рендер брал системный шрифт (на Mac —
Helvetica). Nimbus Sans (URW base35) — метрический клон Helvetica с кириллицей —
возвращает привычный вид, оставаясь детерминированным. Тем, кому нужен буквально
прежний вид «как на моей машине», нужен явный путь отката на системные шрифты.

## What Changes

- Вендорный шрифт заменяется: Liberation Sans → **Nimbus Sans** (4 начертания,
  OTF, релиз urw-base35 20200910, AGPL-3.0 + шрифтовое исключение) в
  `vendor/fonts/`; `DEFAULT_FONT_NAME` обновляется.
- Новая опция **`useSystemFonts`** (bool, default `false`) в `.c4builder` +
  CLI-флаг **`--system-fonts`** (разовое переопределение, приоритет над конфигом):
  при включении пин шрифта снимается в обоих движках — JVM/PlantUML рендерит
  системным шрифтом (как до ветки phoenix), resvg растрирует с
  `loadSystemFonts: true`.
- Кеш рендера учитывает режим шрифта (имя вендорного шрифта или `system`) —
  переключение режима не отдаёт устаревшие картинки из кеша.
- Golden-эталоны пересобираются под Nimbus Sans; golden-контур всегда работает на
  вендорном шрифте (`useSystemFonts` в нём не участвует — системные шрифты
  недетерминированы по определению).
- **BREAKING (визуально):** вид текста диаграмм по умолчанию меняется
  (Arial-метрики → Helvetica-метрики). Поведение сборки и API не меняются.

## Capabilities

### New Capabilities

_нет_

### Modified Capabilities

- `diagram-rendering`: требование «Детерминированные метрики текста через вендорный
  шрифт» — вендорным шрифтом становится Nimbus Sans; добавляется требование
  режима системных шрифтов (опция снимает пин в JVM и resvg, кеш различает режимы).
  Ключ `useSystemFonts` в схеме `.c4builder` — реализация существующего требования
  `config-validation` («схема — единый источник»), его дельта не нужна.

## Impact

- `vendor/fonts/*` + `vendor/fonts/README.md` — замена файлов, происхождение/лицензия.
- `src/core/render/fonts.ts` — имя шрифта; `src/core/render/diagrams.ts` — условная
  передача JVM-флагов шрифта и ключ кеша; `src/core/render/pngraster.ts` — условный
  `loadSystemFonts`.
- `src/config/schema.ts`, `defaults.ts`, `options.ts` — ключ `useSystemFonts`;
  `src/cli/dispatch.ts` — флаг `--system-fonts`.
- `test/golden/*` — пересборка эталонов; golden остаётся на linux-контуре CI
  (матрица ОС не добавляется), CFF на windows/macos не проверяется — план Б при
  жалобе: конвертация OTF→TTF на этапе вендоринга.
- Docker-образ подхватывает новые файлы из `vendor/fonts/` автоматически.
- Потребитель `arch`: конфиг не меняется, сборка совместима; меняется только
  внешний вид текста.

## design

[Обзор](#C4-Builder)

# Design: heros-font-system-flag

## Context

Пин шрифта живёт в одной точке — `src/core/render/fonts.ts` (`FONTS_DIR`,
`DEFAULT_FONT_NAME = 'Liberation Sans'`) — и применяется в двух движках:

- JVM/PlantUML (`src/core/render/diagrams.ts`): `-Dsun.java2d.fontpath=prepend:`,
  `-SdefaultFontName`, `-SCircledCharacterFontName`;
- resvg (`src/core/render/pngraster.ts`): `fontDirs`, `defaultFontFamily`,
  `loadSystemFonts: false`.

Имя шрифта уже входит в ключ кеша рендера (`diagrams.ts`, `font=...`).
Golden-эталоны собраны под Liberation Sans. Обратная связь: вид диаграмм
изменился по сравнению с системным шрифтом (на Mac — Helvetica).

## Goals / Non-Goals

**Goals:**

- Дефолтный вид текста — метрический клон Helvetica (Nimbus Sans), детерминизм
  сохраняется.
- Явный откат на системные шрифты: ключ `useSystemFonts` в `.c4builder` +
  разовый CLI-флаг `--system-fonts`.
- Кеш не смешивает режимы; golden остаётся зелёным и детерминированным.

**Non-Goals:**

- Произвольный пользовательский шрифт (ключ `fontName` с путём к TTF) — не делаем,
  YAGNI; появится по реальному запросу.
- Детерминизм в режиме системных шрифтов — принципиально невозможен и не обещается.
- Смена шрифта ditaa — его движок берёт AWT-шрифт мимо опций пина (как сейчас).

## Decisions

1. **Шрифт — Nimbus Sans (URW base35, релиз 20200910), 4 начертания OTF.**
   Первым кандидатом был TeX Gyre Heros (GUST FL), но он **не содержит кириллицы**
   (проверено `fc-scan`: в 2.004 нет ни `ru`, ни диапазона U+04xx) — с ним PNG
   русских диаграмм рендерился бы пустотой, а метрики кириллицы уходили бы мимо
   вендорного шрифта. Nimbus Sans — тот же метрический клон Helvetica, но с
   кириллицей и греческим. Цена — лицензия AGPL-3.0-only с шрифтовым исключением
   (`PS-or-PDF-font-exception-20170817`) вместо GUST FL; решение принято осознанно.
   Остаться на Liberation Sans — не закрывает фидбэк (клон Arial, не Helvetica).
   Происхождение и версия фиксируются в `vendor/fonts/README.md`.

2. **OTF (CFF-кривые) вшиваем как есть, без конвертации.**
   AWT читает CFF с Java 7, resvg — тоже; на linux подтверждено golden-прогоном
   (метрики Nimbus в SVG, кириллица в PNG). Матрицу ОС в CI не добавляем — golden
   остаётся на пинованном ubuntu-24.04, риск CFF на windows/macos принят. План Б
   по факту жалобы: одноразовая конвертация OTF→TTF (fontforge) на этапе
   вендоринга; конвертация в сборку не входит.

3. **Опция — `useSystemFonts: boolean` (default `false`) в `.c4builder` +
   CLI-флаг `--system-fonts` как разовое переопределение (флаг сильнее конфига).**
   Конфиг — для репозиториев, где старый вид нужен постоянно (контракт arch не
   трогаем: отсутствие ключа = вендорный шрифт). Флаг — для «отрендерить разок
   как раньше» без правки конфига. Оба стоят копейки: bool в zod-схеме +
   `.option()` в commander.

4. **Механика отключения пина — просто не передавать его.**
   JVM: три шрифтовых аргумента не добавляются в argv → PlantUML ведёт себя как
   до ветки phoenix (системный fontconfig). resvg: `loadSystemFonts: true`, без
   `fontDirs`/`defaultFontFamily`. Никаких «пустых значений» и промежуточных
   абстракций — условное включение трёх строк в argv и одного поля опций.

5. **Ключ кеша: `font=<имя>` → в системном режиме `font=system`.**
   Механизм уже существует, меняется только значение — переключение режима
   автоматически промахивается мимо кеша другого режима. Версию схемы кеша
   поднимать не нужно.

6. **Golden — только вендорный шрифт.**
   Эталоны пересобираются один раз под Nimbus Sans. `useSystemFonts` в golden-контуре
   не участвует: системные шрифты недетерминированы, их фиксация невозможна.
   Покрытие системного режима — unit-тест на argv/опции рендера (флаги шрифта
   отсутствуют), не пиксельная сверка.

## Risks / Trade-offs

- [CFF-шрифт не подхватится AWT на windows/macos] → в CI не проверяется (golden
  только на linux); ловится по жалобе, план Б — TTF-конвертация (решение 2).
- [Имя семейства в name-таблице OTF не совпадёт с ожиданием AWT/resvg
  (`Nimbus Sans`)] → сверено `fc-scan` при вендоринге (все 4 начертания дают
  `Nimbus Sans` + языки `ru/uk/el`); имя задаётся единственной константой
  `DEFAULT_FONT_NAME`.
- [AGPL-файлы шрифта в публикуемом npm-пакете] → шрифтовое исключение покрывает
  встраивание в документы; код пакета остаётся под своей лицензией (агрегат),
  происхождение и лицензия зафиксированы в `vendor/fonts/README.md`.
- [В системном режиме на голой машине/в докере нет шрифтов → JVM logical font /
  пустой fontconfig] → это ожидаемое свойство режима «как раньше», фиксируем в
  README одним предложением; дефолт остаётся детерминированным.
- [Метрики Nimbus Sans ≠ Liberation → у arch изменится геометрия всех диаграмм] →
  осознанное следствие фидбэка; ничего в конфиге arch менять не нужно.

## Migration Plan

1. Заменить файлы в `vendor/fonts/` + README (происхождение, лицензия).
2. `DEFAULT_FONT_NAME` → `'Nimbus Sans'`; опция и флаг; условный пин.
3. Пересобрать golden-эталоны, прогнать golden-matrix на трёх ОС.
4. Откат — revert коммита: шрифт, эталоны и ключ кеша вернутся согласованно.

## Open Questions

Нет — дефолт-шрифт подтверждён пользователем: Nimbus Sans (Heros отпал из-за
отсутствия кириллицы; JetBrains Mono моноширинный, JetBrains Sans проприетарный).

## tasks

[Обзор](#C4-Builder)

# Tasks: heros-font-system-flag

## 1. Вендоринг Nimbus Sans

- [x] 1.1 Скачать Nimbus Sans (regular, bold, italic, bolditalic; OTF) из urw-base35 (Artifex), положить в `vendor/fonts/`, удалить LiberationSans-*.ttf
- [x] 1.2 Сверить имя семейства в name-таблице (`fc-scan`) с константой `Nimbus Sans`, кириллицу — по `%{lang}`
- [x] 1.3 Обновить `vendor/fonts/README.md`: происхождение, версия, лицензия AGPL-3.0 + font exception

## 2. Опция useSystemFonts

- [x] 2.1 `src/config/schema.ts` + `defaults.ts` + `options.ts`: ключ `useSystemFonts` (bool, default `false`) → опция сборки `USE_SYSTEM_FONTS`
- [x] 2.2 `src/cli/dispatch.ts`: флаг `--system-fonts`, переопределяющий значение из конфига (флаг сильнее ключа)

## 3. Рендер

- [x] 3.1 `src/core/render/fonts.ts`: `DEFAULT_FONT_NAME = 'Nimbus Sans'`
- [x] 3.2 `src/core/render/diagrams.ts`: три шрифтовых аргумента JVM добавляются в argv только при выключенном `USE_SYSTEM_FONTS`; ключ кеша — `font=system` в системном режиме
- [x] 3.3 `src/core/render/pngraster.ts`: при `USE_SYSTEM_FONTS` — `loadSystemFonts: true`, без `fontDirs`/`defaultFontFamily`
- [x] 3.4 Unit-тест: argv рендера и опции растеризатора в обоих режимах (пин присутствует/отсутствует), кеш-ключи различаются

## 4. Golden и CI

- [x] 4.1 Пересобрать golden-эталоны под Nimbus Sans, закоммитить
- [x] 4.2 Golden прогнан на linux (контур CI, ubuntu-24.04) — зелёный, метрики Nimbus применились. Матрицы windows/macos в CI нет и не добавляем: риск CFF на них принят, план Б (конвертация OTF→TTF fontforge + повтор 1.2–4.1) выполняется по факту жалобы
- [x] 4.3 README: абзац про `useSystemFonts`/`--system-fonts` и оговорку о машинозависимости системного режима

## specs

[Обзор](#C4-Builder)

- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-24-nimbus-font-system-flag/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Обзор](#C4-Builder)

# Delta: diagram-rendering — шрифт Nimbus Sans и режим системных шрифтов

## MODIFIED Requirements

### Requirement: Детерминированные метрики текста через вендорный шрифт
Ширина текста в SVG зависит от метрик шрифта, поэтому сборка SHALL по умолчанию
использовать шрифт Nimbus Sans, поставляемый в составе репозитория
(`vendor/fonts/`), и задавать его как шрифт диаграмм по умолчанию. Шрифт MUST
физически предоставляться JVM (а не только задаваться по имени), чтобы исключить
молчаливый откат на системный шрифт. Пин действует, когда режим системных шрифтов
выключен (`useSystemFonts=false`, значение по умолчанию).

#### Scenario: Рендер использует вендорный шрифт
- **WHEN** выполняется сборка на машине, где заданный шрифт не установлен системно
- **THEN** рендер использует шрифт из `vendor/fonts/`, а не системный fallback

#### Scenario: Повторяемость метрик
- **WHEN** одна и та же диаграмма рендерится дважды на одной машине
- **THEN** геометрия выходного SVG (координаты и `textLength`) байт-в-байт идентична

### Requirement: Детерминированная растеризация PNG с вендорным шрифтом
Растеризатор SVG→PNG SHALL в режиме по умолчанию (`useSystemFonts=false`)
использовать шрифт из состава репозитория (`vendor/fonts/`) и MUST NOT подгружать
системные шрифты, чтобы текст (включая кириллицу) рендерился одинаково независимо
от машины. Повторная растеризация одного SVG на одной версии растеризатора MUST
давать байт-в-байт идентичный PNG. В режиме системных шрифтов растеризатор SHALL
загружать системные шрифты и MUST NOT навязывать вендорное семейство.

#### Scenario: Кириллица в PNG
- **WHEN** диаграмма с кириллическим текстом растеризуется в PNG
- **THEN** кириллица корректно отрисована шрифтом из `vendor/fonts/`, а не системным fallback

#### Scenario: Повторяемость PNG
- **WHEN** один и тот же SVG растеризуется дважды на одной машине
- **THEN** оба PNG байт-в-байт идентичны

#### Scenario: PNG в режиме системных шрифтов
- **WHEN** растеризация выполняется при включённом `useSystemFonts`
- **THEN** растеризатор загружает системные шрифты, вендорное семейство не задаётся

## ADDED Requirements

### Requirement: Режим системных шрифтов
Сборка SHALL поддерживать режим системных шрифтов: ключ `useSystemFonts`
(boolean, по умолчанию `false`) в `.c4builder` и CLI-флаг `--system-fonts`,
разово включающий режим независимо от конфига (флаг сильнее ключа). При
включённом режиме рендер MUST NOT передавать JVM шрифтовые аргументы
(`-Dsun.java2d.fontpath`, `-SdefaultFontName`, `-SCircledCharacterFontName`) —
PlantUML использует системный шрифт, как до вендорного пина. Ключ кеша рендера
MUST различать режимы шрифта: результат одного режима MUST NOT отдаваться из
кеша в другом. Вывод в этом режиме машинозависим — это ожидаемо и
детерминизм для него NOT гарантируется.

#### Scenario: Флаг включает системные шрифты поверх конфига
- **WHEN** в `.c4builder` ключ `useSystemFonts` отсутствует или равен `false`, но сборка запущена с `--system-fonts`
- **THEN** JVM запускается без шрифтовых аргументов, растеризатор использует системные шрифты

#### Scenario: Отсутствие ключа — прежнее поведение
- **WHEN** `.c4builder` не содержит ключ `useSystemFonts` (например, конфиг репо arch)
- **THEN** рендер идёт с вендорным шрифтом, поведение сборки не отличается от режима по умолчанию

#### Scenario: Кеш не смешивает режимы
- **WHEN** одна и та же диаграмма рендерится сначала в режиме по умолчанию, затем с `--system-fonts`
- **THEN** второй рендер не берёт результат первого из кеша (и наоборот)

#### Scenario: Golden-контур не зависит от режима
- **WHEN** выполняются golden-тесты
- **THEN** они рендерят вендорным шрифтом; режим системных шрифтов покрыт проверкой аргументов рендера, а не пиксельной сверкой

## 2026-07-09-tag-driven-rc-publish

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-08 · **Tasks:** <progress value="12" max="12"></progress> 12/12 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-09-tag-driven-rc-publish/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-09-tag-driven-rc-publish/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-09-tag-driven-rc-publish/specs/specs)

## Why

Текущий workflow публикации (`.github/workflows/publish.yml`) срабатывает на каждый push в `master` и всегда публикует в dist-tag `latest` — то есть любая опубликованная версия немедленно прилетает всем по `npm install`. Для ветки `refactor/phoenix` (крупный рефактор) нужен способ выпускать релиз-кандидаты, которые ставятся только осознанно и не задевают текущих пользователей `0.2.x`.

## What Changes

- **BREAKING** (для релизного процесса): публикация переводится с триггера «push в master» на триггер «push git-тега `v*`». Обычные коммиты и мержи в master больше НЕ публикуют пакет.
- Dist-tag выбирается по версии из `package.json`: пререлиз (версия содержит `-`, например `0.3.0-rc.1`) → `npm publish --tag rc`; стабильная версия (`0.3.0`) → публикация в `latest`.
- Добавляется гейт синхронизации: строка git-тега MUST совпадать с версией из `package.json` (`v<version>`), иначе workflow падает — защита от рассинхрона тега и публикуемой версии.
- Сохраняется гейт идемпотентности: если версия уже опубликована в npm, шаг публикации пропускается (повторный запуск джобы не падает с конфликтом).
- Сохраняются OIDC trusted publishing и `--provenance` (без новых секретов).
- README дополняется секциями про установку релиз-кандидата (`npm i @alfacapital-tech/c4builder@rc`) и про релизный процесс (`## Releasing`); заодно исправляется устаревшее имя пакета в install-секции (`c4builder` → `@alfacapital-tech/c4builder`).

## Capabilities

### New Capabilities
- `release-publishing`: публикация npm-пакета через GitHub Actions — тег-драйв триггер, выбор dist-tag по семантике версии (rc для пререлизов, latest для стабильных), гейты синхронизации тег↔версия и идемпотентности, provenance.

### Modified Capabilities
<!-- Нет: публикация пакета ранее не была описана в specs; ci-validation покрывает только тестовый workflow и не затрагивается. -->

## Impact

- **Файлы**: `.github/workflows/publish.yml` (переписывается: триггер, гейты, выбор dist-tag), `README.MD` (секции про `@rc` и `## Releasing` + фикс имени пакета).
- **Релизный процесс**: выпуск RC — `npm version 0.3.0-rc.N` + `git push --follow-tags` с ветки `refactor/phoenix` (без мержа в master); финал — `npm version 0.3.0` + тег. Мерж phoenix→master публикацию не триггерит.
- **Потребители**: `npm install @alfacapital-tech/c4builder` продолжает получать `latest` (`0.2.25`); пререлизы доступны только по `@rc` или точной версии и исключены из диапазонов `^0.2.x`.
- **CI-тесты** (`ci.yml`) и рендер не затрагиваются.

## design

[Обзор](#C4-Builder)

## Context

Пакет `@alfacapital-tech/c4builder` публикуется в npm через `.github/workflows/publish.yml`. Текущая логика: триггер `push` в `master` + `workflow_dispatch`; шаг публикации сравнивает `npm view … version` (это `latest`) с версией из `package.json` и при различии делает `npm publish --provenance --access public` — **без `--tag`, то есть всегда в `latest`**. Аутентификация — OIDC trusted publishing (`id-token: write`), статических токенов нет.

Готовится крупный рефактор в ветке `refactor/phoenix`. Нужно публиковать релиз-кандидаты так, чтобы они не попадали к пользователям `0.2.x` через `npm install`, но были доступны тестерам осознанно.

Опубликованное состояние на момент change: `latest = 0.2.25`, `package.json = 0.2.25`.

## Goals / Non-Goals

**Goals:**
- Публикация происходит только по явному действию — push git-тега `v*`.
- Пререлизы (`0.3.0-rc.N`) публикуются под dist-tag `rc`, не смещая `latest`.
- Стабильные версии публикуются в `latest`.
- Защита от рассинхрона строки тега и версии в `package.json`.
- Повторный запуск workflow для уже опубликованной версии не падает.
- Provenance и OIDC сохраняются без новых секретов.

**Non-Goals:**
- Автоматический bump версии в CI (версию задаёт разработчик через `npm version` локально).
- Изменение тестового workflow `ci.yml` и логики рендера.
- Введение нескольких пререлизных каналов (`beta`, `next`) — сейчас только `rc`.
- Автоматический changelog / GitHub Releases.

## Decisions

### D1. Триггер: push git-тега `v*` вместо push в master

Публикация вешается на `on: push: tags: ['v*']` (+ `workflow_dispatch`). Триггер `push` в `master` **убирается**.

Почему: публикация становится явным намерением (push тега), а не побочным эффектом мержа. Тег может указывать на коммит ветки `refactor/phoenix` — RC выпускается без мержа в master. Убирая master-триггер, исключаем двойную публикацию (тег + мерж финала).

Альтернативы:
- *Триггер на ветку `refactor/phoenix`* — публиковал бы на каждый коммит (шумно), и опасный «version-diff» гейт мог бы протолкнуть пререлиз в `latest`. Отклонено.
- *Оставить master-триггер параллельно с тегами* — риск двойной публикации финала. Отклонено.

### D2. Выбор dist-tag по семантике версии

Версия читается из `package.json`. Наличие `-` = пререлиз → `npm publish --tag rc`. Иначе → публикация в `latest` (без `--tag`). Извлечение выполняется простой проверкой строки версии в shell.

Почему `rc` фиксированным словом, а не парсингом preid: у нас единственный пререлизный канал; жёсткое `rc` проще и исключает опечатки в теге. (При версии `0.3.0-rc.1` npm-семантика пререлиза сама по себе исключает её из диапазонов `^0.2.x` — это второй, независимый слой защиты помимо dist-tag.)

### D3. Гейт синхронизации тег↔версия

Перед публикацией: `test "v$(node -p 'require("./package.json").version')" = "$GITHUB_REF_NAME"`, иначе `exit 1`.

Почему: `npm publish` берёт версию из `package.json`, игнорируя строку git-тега. Без гейта тег `v0.3.0-rc.1` при забытом bump опубликовал бы `0.2.25`. Это единственный реальный footgun схемы. Эргономический контур `npm version <v>` (правит `package.json` + коммит + тег синхронно) предотвращает рассинхрон на входе, гейт — страховка на случай ручного тега.

### D4. Гейт идемпотентности (сохраняется)

Оставляем проверку из текущего workflow: `CURRENT=$(npm view … version …)` vs `LOCAL`; если версия уже в реестре — skip. Уточнение под пререлизы: сравнение должно учитывать, что публикуемая версия может быть пререлизной, поэтому проверяем присутствие конкретной версии в реестре (`npm view <pkg>@<version> version`), а не только `latest`.

### D5. Provenance / OIDC без изменений

`permissions: id-token: write`, `npm publish --provenance --access public`, `registry-url: https://registry.npmjs.org`. Модель аутентификации не меняется.

## Risks / Trade-offs

- **Рассинхрон тег↔версия** → гейт D3 + рекомендованный флоу `npm version`.
- **Пуш стабильного тега ниже текущего `latest`** (например `v0.2.24`) сместил бы `latest` назад → на практике npm не даст переопубликовать существующую версию (гейт D4 → skip); дисциплина версий. Отдельный guard не вводим (overkill).
- **Гейт идемпотентности по `latest` вместо конкретной версии** дал бы ложный «нужно публиковать» для пререлиза → D4 уточнён на проверку присутствия конкретной версии.
- **Забыли `--tag rc` для пререлиза** → пререлиз ушёл бы в `latest`; предотвращается тем, что выбор тега вычисляется автоматически из версии (D2), а не задаётся руками.

## Migration Plan

1. Переписать `.github/workflows/publish.yml`: триггер (D1), гейт синхронизации (D3), выбор dist-tag (D2), уточнённый гейт идемпотентности (D4), сохранить OIDC/provenance (D5).
2. Дополнить `README.MD` секцией про установку `@rc`.
3. Проверка вживую: с ветки `refactor/phoenix` — `npm version 0.3.0-rc.1 -m "rc: %s"` + `git push --follow-tags`; убедиться, что опубликовано под `rc`, а `latest` остался `0.2.25` (`npm view @alfacapital-tech/c4builder dist-tags`).

Откат: вернуть предыдущую версию `publish.yml` (git revert); опубликованные пререлизы при необходимости снять `npm dist-tag rm … rc` / депрекейтнуть.

## Open Questions

- Нужен ли отдельный шаг создания GitHub Release по тегу — вне scope этого change (можно добавить позже).

## tasks

[Обзор](#C4-Builder)

## 1. Переписать workflow публикации

- [x] 1.1 В `.github/workflows/publish.yml` заменить триггер: убрать `push: branches: [master]`, поставить `push: tags: ['v*']`; сохранить `workflow_dispatch`
- [x] 1.2 Добавить шаг-гейт синхронизации: `test "v$(node -p 'require("./package.json").version')" = "$GITHUB_REF_NAME"`, иначе `exit 1` (D3)
- [x] 1.3 Реализовать выбор dist-tag: версия содержит `-` → `npm publish --tag rc --provenance --access public`; иначе → `npm publish --provenance --access public` (latest) (D2)
- [x] 1.4 Уточнить гейт идемпотентности: проверять присутствие конкретной версии (`npm view <pkg>@<version> version`), а не `latest`; при наличии — skip (D4)
- [x] 1.5 Сохранить `permissions: id-token: write`, `registry-url`, `--provenance`, `npm ci --ignore-scripts` (D5)

## 2. Документация

- [x] 2.1 Добавить в `README.MD` короткую секцию: установка релиз-кандидата `npm i @alfacapital-tech/c4builder@rc` и что `npm install` без тега ставит стабильную версию
- [x] 2.2 Добавить в `README.MD` секцию `## Releasing`: выпуск rc (`npm version 0.3.0-rc.N -m "rc: %s"` + `git push --follow-tags` с ветки `refactor/phoenix`, без мержа в master) и финала (`npm version 0.3.0` + тег → `latest`)
- [x] 2.3 Исправить неверное имя пакета в install-секции `README.MD` (строка ~31): `npm i -g c4builder` → `npm i -g @alfacapital-tech/c4builder` (пре-существующий баг, чинится заодно)

## 3. Проверка вживую

- [x] 3.1 С ветки `refactor/phoenix`: `npm version 0.3.0-rc.1 -m "rc: %s"` + `git push --follow-tags`
- [x] 3.2 Убедиться, что workflow опубликовал пакет под dist-tag `rc`, а `latest` остался `0.2.25` (`npm view @alfacapital-tech/c4builder dist-tags`)
- [x] 3.3 Проверить, что `npm install @alfacapital-tech/c4builder@rc` ставит `0.3.0-rc.1`, а `npm install` без тега — `0.2.25`
- [x] 3.4 Проверить гейты: повторный запуск для той же версии → skip без ошибки (проверено вживую) — тег с несовпадающей версией → exit 1 проверено dry-run в shell (живой прогон в CI пропущен по решению пользователя, чтобы не пушить лишний тег в публичный репозиторий)

## specs

[Обзор](#C4-Builder)

- [release-publishing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-09-tag-driven-rc-publish/specs/release-publishing/release-publishing)

## release-publishing

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Публикация запускается только push-ем git-тега версии

Публикация пакета в npm SHALL выполняться GitHub Actions workflow, триггер которого — исключительно push git-тега вида `v*` (например `v0.3.0-rc.1`, `v0.3.0`), плюс ручной `workflow_dispatch`. Workflow MUST NOT публиковать пакет по событию `push` в `master` или по мержу ветки. Обычные коммиты и мержи в `master` MUST NOT приводить к публикации.

#### Scenario: Push тега версии
- **WHEN** в репозиторий пушится git-тег `v0.3.0-rc.1`
- **THEN** workflow публикации запускается и выполняет шаг публикации пакета

#### Scenario: Push/мерж в master
- **WHEN** выполнен push или мерж ветки в `master` без нового тега `v*`
- **THEN** workflow публикации не запускается и пакет не публикуется

### Requirement: Dist-tag выбирается по семантике версии

Workflow MUST определять dist-tag по версии из `package.json`: если версия — пререлиз (содержит `-`, например `0.3.0-rc.1`), публикация выполняется командой `npm publish --tag rc`; если версия стабильная (без `-`, например `0.3.0`), публикация выполняется в dist-tag `latest`. Это гарантирует, что пререлизы не смещают `latest` и не попадают в `npm install` без явного запроса.

#### Scenario: Публикация пререлиза
- **WHEN** публикуется версия `0.3.0-rc.1`
- **THEN** пакет публикуется под dist-tag `rc`, а `latest` остаётся на прежней стабильной версии

#### Scenario: Публикация стабильной версии
- **WHEN** публикуется версия `0.3.0` без суффикса пререлиза
- **THEN** пакет публикуется в dist-tag `latest`

#### Scenario: Установка релиз-кандидата
- **WHEN** пользователь выполняет `npm install @alfacapital-tech/c4builder@rc`
- **THEN** ставится последняя версия под тегом `rc`, тогда как `npm install` без тега продолжает ставить `latest`

### Requirement: Гейт синхронизации тега и версии

Перед публикацией workflow MUST проверять, что строка git-тега совпадает с версией из `package.json` в форме `v<version>`. При несовпадении workflow MUST завершаться с ошибкой и НЕ публиковать пакет — это защита от рассинхрона, при котором `npm publish` опубликовал бы версию из `package.json`, не совпадающую с намерением тега.

#### Scenario: Тег совпадает с версией
- **WHEN** тег `v0.3.0-rc.1`, а версия в `package.json` — `0.3.0-rc.1`
- **THEN** гейт проходит и workflow переходит к публикации

#### Scenario: Тег не совпадает с версией
- **WHEN** тег `v0.3.0-rc.1`, а версия в `package.json` — `0.2.25`
- **THEN** workflow завершается с ненулевым кодом и ничего не публикует

### Requirement: Идемпотентность публикации

Workflow MUST пропускать шаг публикации, если версия из `package.json` уже опубликована в npm-реестре. Повторный запуск workflow для уже опубликованной версии MUST завершаться успешно без попытки повторной публикации (без ошибки конфликта).

#### Scenario: Версия уже опубликована
- **WHEN** workflow запущен для версии, которая уже присутствует в реестре
- **THEN** шаг публикации пропускается, workflow завершается успешно

#### Scenario: Новая версия
- **WHEN** workflow запущен для версии, которой ещё нет в реестре
- **THEN** пакет публикуется под соответствующим dist-tag

### Requirement: Сохранение provenance и trusted publishing

Workflow MUST публиковать пакет с `--provenance` через OIDC trusted publishing (`permissions: id-token: write`), без хранения долгоживущих npm-токенов в секретах репозитория. Модель аутентификации MUST оставаться неизменной при переходе на тег-драйв.

#### Scenario: Публикация с provenance
- **WHEN** выполняется шаг публикации пакета
- **THEN** пакет публикуется с флагом `--provenance` и аутентификацией через OIDC, без использования статического npm-токена

## 2026-07-08-zod-and-deps-upgrade

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-07 · **Tasks:** <progress value="13" max="13"></progress> 13/13 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/specs/specs)

# zod-and-deps-upgrade — рантайм-валидация конфига и апгрейд зависимостей

## Why

`.c4builder` читается «оптимистично»: `BuildOptions` типизирован как заведомо полный,
но рукописный/неполный конфиг молча даёт поля `undefined` и тихо неверную сборку
вместо понятной ошибки (см. обещание zod в комментарии `config/options.ts`).
Параллельно рантайм-зависимости устарели и несут 5 npm-уязвимостей (`lodash` high
транзитивно через `inquirer@8`; `qs`/`body-parser` через `express@4`; `joi`), а сам
`joi` дублирует роль будущего валидатора. Оба долга помечены как отдельное звено
после `ts-port-full`/`build-split` — время закрыть.

## What Changes

- **Новая рантайм-валидация `.c4builder` через zod**: единая схема ключей конфига
  (camelCase) с парсингом и coercion при загрузке в `getOptions()`; неполный/битый
  конфиг отклоняется понятной ошибкой вместо `undefined`-полей. `BuildOptions`
  перестаёт быть «оптимистичным» типом — становится выводом zod-схемы.
- **`joi` → zod в мастере** (`cli/wizard/collect.ts`): валидация ответов визарда
  переезжает на zod; **`joi` удаляется** (уносит свою уязвимость).
- **BREAKING (внутренние API библиотек, не CLI): апгрейд зависимостей**:
  - `inquirer` 8 → 12 (ESM; легаси `.prompt([...])`-API сохранён, `lodash` выкинут в v9+) —
    `collect.ts` адаптируется точечно, без переписывания на функциональный API;
  - `express` 4 → 5 (роутинг на path-to-regexp v8) — правится `cli/commands/site.ts`
    (wildcard-маршрут раздачи статики);
  - ESM-версии: `chalk` 2 → 5, `open` 8 → 10, `configstore` 4 → 7;
  - `commander` 14 → 15 (мажор без уязвимостей, API стабилен);
  - минорные подтяжки: `figlet`, `fs-extra`, `@types/*` в лад.
- **Закрытие 5 npm-уязвимостей** апгрейдами выше (drop `joi`; транзитивный `lodash`
  уходит с новым `inquirer`; `qs`/`body-parser` — с `express@5`).
- **Аудит-гейт на CI**: `npm audit` (уровень ≥ high) отдельной джобой — уязвимости
  не возвращаются молча в последующих PR.
- Наблюдаемое поведение CLI-сборки не меняется: golden зелёный (валидация конфига
  и визард — CLI-поверхность, а не выход конвейера сборки).

## Capabilities

### New Capabilities

- `config-validation`: рантайм-валидация `.c4builder` по zod-схеме при загрузке —
  понятные ошибки на неполный/битый конфиг, честный coercion значений, единый
  источник формы конфига (вместо «оптимистичного» `BuildOptions`).

### Modified Capabilities

- `dev-toolchain`: добавляется требование — рантайм-зависимости поддерживаются
  актуальными и без известных уязвимостей уровня ≥ high; регресс ловится
  `npm audit`-гейтом на CI.

## Impact

- **Зависимости**: +`zod`; −`joi`; апгрейд `inquirer`/`express`/`chalk`/`open`/
  `configstore`/`commander`/`figlet`/`fs-extra` и соответствующих `@types/*`;
  уходит транзитивный `lodash`.
- **Код**: новый `config/schema.ts` (zod-схема + вывод типов); правка `cli/dispatch.ts`
  (`getOptions` валидирует через схему); `cli/wizard/collect.ts` (zod-валидация +
  новый inquirer API); `cli/commands/site.ts` (роутинг express 5). Точечно — вызовы
  `chalk`/`open`/`configstore` под новые ESM-версии.
- **CI**: новая джоба `audit` в `.github/workflows/ci.yml`.
- **Поведение/конфиг**: формат `.c4builder` не меняется (та же схема ключей, те же
  дефолты и coercion); golden зелёный без регенерации эталонов.
- **Не входит**: TeaVM, новые фичи рендера, изменение формата `.c4builder`. Библиотеки
  `node-watch`/`tar`/`yauzl`/`@resvg` не трогаем — они уже на latest и чисты по аудиту
  (апгрейд не требуется, это не отложенная работа).

## design

[Обзор](#C4-Builder)

## Context

`.c4builder` читается «оптимистично»: `getOptions()` в `cli/dispatch.ts` собирает
`BuildOptions` из configstore, а тип объявлен как заведомо полный (комментарий в
`config/options.ts` прямо помечает это как долг под zod). Рукописный/неполный конфиг
даёт `undefined`-поля и тихо неверную сборку. Параллельно рантайм-зависимости
устарели: `inquirer@8` тянет `lodash` (high CVE), `express@4` — `qs`/`body-parser`
(moderate), `joi@17` несёт свою moderate и дублирует роль валидатора. Код уже строгий
TS + ESM (после `ts-port-full`), golden-матрица фиксирует выход конвейера сборки.

## Goals / Non-Goals

**Goals:**
- Единая zod-схема формы `.c4builder` + честная валидация при загрузке: понятная
  ошибка на неверный тип значения, дефолты на отсутствующие поля.
- `joi` вытеснен zod в мастере и удалён из зависимостей.
- Рантайм-зависимости подняты до актуальных; 5 известных уязвимостей закрыты;
  регресс ловится `npm audit`-гейтом на CI.
- Поведение CLI-сборки и формат `.c4builder` не меняются: golden зелёный без
  регенерации эталонов.

**Non-Goals:**
- Изменение формата/ключей `.c4builder`, набора опций, дефолтов.
- Переписывание визарда на функциональный `@inquirer/prompts` (легаси-API v12 достаточно).
- Замена `commander`/`node-watch`/`tar`/`yauzl`/`@resvg`; TeaVM; новые фичи рендера.

## Decisions

**zod валидирует сырой `.c4builder` (camelCase), маппинг в `BuildOptions` сохраняется.**
Новый `config/schema.ts` описывает схему ключей файла (`C4ConfigFile`) — все поля
опциональны с дефолтами из `defaultConfig` и coercion типов; пустой/частичный конфиг
проходит (дефолты подставляются), неверный тип значения → `safeParse` ошибка с путём
ключа. `getOptions()` берёт `conf.all` (или эквивалент), прогоняет через схему и
маппит валидированные ключи в `BuildOptions` (SCREAMING_CASE) — существующая логика
маппинга (спец-кейс `WEB_THEME`, `D2_LAYOUT || 'dagre'`, константа `MD_FILE_NAME`)
переносится как есть. Тип `BuildOptions` перестаёт быть «оптимистичным» — выводится/
проверяется схемой.
- *Альтернатива (отвергнута):* zod-схема сразу отдаёт `BuildOptions` через `.transform`
  — смешивает валидацию с маппингом, дифф хуже читается, риск разойтись с текущими
  дефолтами. Разделение «валидировать сырое → маппить» безопаснее для golden.

**Первый запуск/`--new`: схема лояльна к пустому конфигу.** В `--new`/first-run
`getOptions()` вызывается на конфиг-заглушке до визарда. Все поля опциональны-с-дефолтом,
поэтому пустой ввод валиден (ошибка — только на явно неверный тип), и текущее поведение
(отсутствует → дефолт/визард дозаполняет) сохраняется.

**`joi` → zod в валидаторах визарда.** `validate()`-обёртка в `cli/wizard/collect.ts`
переходит на zod (`schema.safeParse(answer)` → boolean / строка ошибки для inquirer).
Мёртвая легаси-ветка `joi.validate` удаляется вместе с `joi`.

**`inquirer` 8 → 12 минимально.** v9+ ESM и без `lodash`; легаси `inquirer.prompt([...])`
сохранён и покрывает используемые типы (`input`/`checkbox`/`confirm`). Меняем только
несовместимости (ESM-импорт, типы ответов), не переписывая на функциональный API.
`@types/inquirer` удаляется — пакет несёт свои типы.
- *Альтернатива (отвергнута):* полный переход на `@inquirer/prompts` — больше диффа и
  риска ради стиля; не нужно для цели change'а.

**`express` 4 → 5: статика через `app.use`, без wildcard-маршрута.** path-to-regexp v8
запрещает голый `'/*'`. В `cli/commands/site.ts` финальный `app.get('/*', express.static(dist))`
меняется на `app.use(express.static(dist))` (тот же эффект раздачи, без именованного
wildcard). Остальные вызовы (`res.set/write/send/type`, `app.listen`, `app.get(LIVERELOAD_PATH)`,
кастомный `app.use`-middleware livereload) в express 5 стабильны — сверяются при apply.

**ESM-апгрейды точечно.** `chalk` 2 → 5, `open` 8 → 10, `configstore` 4 → 7 — все
чистый ESM; проект уже ESM, поэтому правки только на несовместимых вызовах (проверяются
tsc). `figlet`/`fs-extra` — минорные.

**`npm audit`-гейт на CI.** Отдельная быстрая джоба `audit` (`npm audit --audit-level=high`,
`--omit=dev` если нужно отсечь dev-шум) — фиксирует «нет известных уязвимостей ≥ high»
как воспроизводимое требование, не разовую уборку.

## Risks / Trade-offs

- **[zod-дефолты/coercion разойдутся с текущими → golden покраснеет]** → схема повторяет
  `defaultConfig` дословно; golden гоняется после zod-звена; расхождение = ошибка переноса,
  не смены поведения.
- **[express 5 несёт и другие breaking-изменения (query parser, удалённые методы)]** →
  инвентаризация вызовов `site.ts` при apply по гайду 4→5; сейчас в коде только стабильное
  подмножество + один wildcard.
- **[inquirer 12 строже типизирует ответы]** → тип ответов через `Awaited<ReturnType<
  typeof inquirer.prompt>>`; точечные касты на месте чтения полей.
- **[audit-гейт покраснеет на новой транзитивной уязвимости без фикса]** → уровень `high`
  + возможность временного allow-list/`--omit=dev`; гейт информирует, а не блокирует навсегда.
- **[ESM-апгрейды ломают импорт/типы]** → ловится tsc (строгий) до тестов; каждый апгрейд —
  отдельный шаг с проверкой.

## Migration Plan

1. `zod` + `config/schema.ts` (схема `.c4builder`, дефолты/coercion); `getOptions()`
   валидирует и маппит; `BuildOptions` от схемы. golden; коммит.
2. `joi` → zod в `collect.ts`; удалить `joi`. golden + прогон визарда; коммит.
3. `inquirer` 8→12 (+ снять `@types/inquirer`); адаптировать `collect.ts`. tsc; коммит.
4. `express` 4→5; починить статику в `site.ts` (`app.use`); проверить serve/livereload вручную. коммит.
5. ESM-апгрейды `chalk`/`open`/`configstore` (+ `figlet`/`fs-extra`, `@types/*`). tsc + golden; коммит.
6. `npm audit`-джоба в CI; `npm audit` чистый локально. финальная проверка (build/golden/pack); коммит.

Откат — по коммитам шагов. Порядок: zod-звено первым (снимает часть долга и даёт
валидацию), апгрейды следом; express и inquirer — независимые шаги.

## Open Questions

- `npm audit` уровень гейта — `high` (предложено) или `moderate`? Уточнить при apply,
  если после апгрейдов останется moderate-шум без доступного фикса.

## tasks

[Обзор](#C4-Builder)

## 1. zod-валидация конфига

- [x] 1.1 Добавить `zod`; создать `src/config/schema.ts`: схема `.c4builder` (camelCase-ключи, все опциональны с дефолтами из `defaultConfig`, coercion типов) + вывод типа формы конфига
- [x] 1.2 `cli/dispatch.ts`: `getOptions()` валидирует сырой конфиг схемой (`safeParse`) — при неверном типе понятная ошибка с ключом (exit ≠ 0), затем маппинг в `BuildOptions` (существующая логика дефолтов/спец-кейсов сохранена); снять «оптимистичность» типа `BuildOptions`
- [x] 1.3 Проверить первый запуск/`--new` (пустой конфиг проходит на дефолтах) и невалидный конфиг (понятная ошибка); golden зелёный; коммит

## 2. joi → zod в визарде

- [x] 2.1 `cli/wizard/collect.ts`: заменить `joi`-валидаторы на zod (`safeParse` → boolean / строка ошибки для inquirer), удалить мёртвую `joi.validate`-ветку
- [x] 2.2 Удалить `joi` из зависимостей; `npm audit` без joi-уязвимости; прогон визарда вручную; коммит

## 3. Апгрейд inquirer 8 → 12

- [x] 3.1 Поднять `inquirer` до 12, снять `@types/inquirer`; адаптировать `collect.ts` под ESM/типы v12 (легаси `.prompt([...])`-API, типы ответов через `Awaited<ReturnType<typeof inquirer.prompt>>`)
- [x] 3.2 Убедиться, что транзитивный `lodash` ушёл (`npm ls lodash` / audit); tsc + biome зелёные; прогон визарда; коммит

## 4. Апгрейд express 4 → 5

- [x] 4.1 Поднять `express` до 5 (+ `@types/express` в лад); в `cli/commands/site.ts` заменить `app.get('/*', express.static(dist))` на `app.use(express.static(dist))`; сверить остальные вызовы по гайду 4→5
- [x] 4.2 Ручная проверка `c4builder --site` (раздача статики, `-w` livereload, `--open`); `qs`/`body-parser`-уязвимости закрыты; tsc; коммит

## 5. ESM-апгрейды и минорные

- [x] 5.1 Поднять `chalk` 2→5, `open` 8→10, `configstore` 4→7 (`@types/configstore` снят — v7 несёт свои типы; `ConfStore.get` выровнен на `T|undefined`), `commander` 14→15; починить несовместимые вызовы (проверка tsc; сверить commander 14→15 breaking по changelog)
- [x] 5.2 Подтянуть `figlet`, `fs-extra`, `@types/*`; tsc + golden зелёные; коммит

## 6. CI аудит-гейт и финальная проверка

- [x] 6.1 Добавить джобу `audit` в `.github/workflows/ci.yml` (`npm audit --audit-level=high --omit=dev`); `npm audit` чистый локально (0 уязвимостей)
- [x] 6.2 Финальная проверка: `npm run build`, весь vitest (golden без регрессий — 7 passed; 3 красных варианта средовые на Arch, идентичны baseline), `biome ci`, `npm pack --dry-run`; коммит

## specs

[Обзор](#C4-Builder)

- [config-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/specs/config-validation/config-validation)
- [dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-08-zod-and-deps-upgrade/specs/dev-toolchain/dev-toolchain)

## config-validation

[Обзор](#C4-Builder)

# config-validation — delta (zod-and-deps-upgrade)

## ADDED Requirements

### Requirement: Рантайм-валидация конфигурации при загрузке

`.c4builder` SHALL валидироваться по схеме при загрузке опций сборки. Значение
неверного типа MUST приводить к понятной ошибке, называющей проблемный ключ, а не
к молчаливому `undefined`-полю. Отсутствующие поля MUST заполняться значениями по
умолчанию — частичный или пустой конфиг остаётся валидным.

#### Scenario: Неверный тип значения отклоняется
- **WHEN** `.c4builder` содержит ключ со значением неверного типа (например, строка вместо булева)
- **THEN** загрузка завершается понятной ошибкой с указанием проблемного ключа, а не тихо продолжает с `undefined`-полем

#### Scenario: Частичный конфиг дополняется дефолтами
- **WHEN** `.c4builder` неполон или пуст (рукописный конфиг либо первый запуск)
- **THEN** отсутствующие поля берут значения по умолчанию и сборка продолжается

#### Scenario: Валидный конфиг не меняет поведение
- **WHEN** валидный `.c4builder` проходит валидацию
- **THEN** результирующие опции сборки совпадают с поведением до введения валидации (golden-эталоны без изменений)

### Requirement: Схема — единый источник формы конфига

Форма `.c4builder` (ключи, типы, значения по умолчанию) SHALL задаваться единой
схемой. Тип опций сборки MUST выводиться из этой схемы или проверяться ею, а не
объявляться «оптимистично» заведомо полным.

#### Scenario: Форма конфига определена в одном месте
- **WHEN** просматривается конфигурационный слой ядра
- **THEN** ключи, типы и дефолты `.c4builder` заданы одной схемой, на которую опирается загрузка опций сборки

## dev-toolchain

[Обзор](#C4-Builder)

# dev-toolchain — delta (zod-and-deps-upgrade)

## ADDED Requirements

### Requirement: Рантайм-зависимости без известных уязвимостей

Рантайм-зависимости SHALL поддерживаться без известных уязвимостей уровня ≥ high.
CI MUST проверять это аудитом зависимостей и давать красный статус при регрессе,
чтобы новая уязвимость не проходила молча.

#### Scenario: Аудит зависимостей на CI
- **WHEN** выполняется CI
- **THEN** отдельная проверка аудита зависимостей проходит только при отсутствии известных уязвимостей уровня ≥ high

#### Scenario: Новая уязвимость ловится
- **WHEN** изменение зависимостей вносит известную уязвимость уровня ≥ high
- **THEN** проверка аудита падает с красным статусом, не пропуская регресс молча

## 2026-07-07-ts-port-full

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="14" max="14"></progress> 14/14 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-ts-port-full/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-ts-port-full/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-ts-port-full/specs/specs)

# ts-port-full — полный порт исходников на TypeScript

## Why

Каркас порта готов (`ts-scaffold`): `src/` — честный ESM, `tsc → dist/`, домены
разложены, но все 16 модулей — ещё `.js`, смесь держится на `allowJs: true`.
Изначально типизация планировалась четырьмя звеньями
(`util+config` → `scan+render` → `compose` → `cli+wizard`), но база мала
(~2600 строк), golden-матрица даёт поведенческую сетку безопасности, а дробление
на четыре change'а — страховка процесса, не техническая необходимость. Решение
пересмотрено (explore-сессия 2026-07-05): порт выполняется одним change,
доменные группы остаются порядком задач внутри него.

## What Changes

- **Все 16 модулей `src/**/*.js` переименовываются в `.ts`** и типизируются под
  уже включённый `strict`. Порядок — по доменам, golden зелёный после каждой
  группы: `config` → `util` → `core` (build, render, compose) → `cli`
  (dispatch, commands, wizard) → `index`.
- **Тип конфига как фундамент.** Новый `src/config/options.ts`: `BuildOptions`
  (SCREAMING_CASE-опции, собираемые `getOptions()`) и тип ключей `.c4builder`.
  Тип оптимистичный (поля обязательны — wizard и `--new --yes` гарантируют
  полноту); честная рантайм-валидация неполных конфигов — отдельное звено `zod`.
- **Типы зависимостей.** `@types/node` + точечные `@types/*` для CJS-зависимостей
  (`configstore`, `inquirer`, `figlet`, `fs-extra`, `express`); при несовпадении
  версии — локальная декларация в `src/types/`.
- **Финальный флип строгости.** После порта последнего домена `allowJs`
  выключается: `.js` в `src/` больше не компилируется, смесь запрещена.
- **`core/build.ts` остаётся монолитом.** Дробление на scan/render/compose —
  отдельный следующий change (`build-split`), уже на типизированной базе.

Не входит: дробление `build.js`, рантайм-валидация конфига (`zod`), апгрейды
зависимостей, починка легаси-дефектов (заглушка `writeOnSameLine`, глотание
ошибок `makeDirectory`, implicit-глобал `responses` и мёртвая joi-валидация в
wizard'е) — легаси типизируется «как есть», рантайм-логика не правится.

## Capabilities

### New Capabilities

Нет: типизация не добавляет наблюдаемого поведения CLI.

### Modified Capabilities

- `build-pipeline`: требование «Исходники на TypeScript и ESM» ужесточается —
  все модули `src/` SHALL быть `.ts`; оговорка «на время порта `allowJs`
  включён» снимается, `allowJs` MUST быть выключен; компиляция MUST проходить
  в режиме `strict`.

## Impact

- Файлы: все `src/**/*.js` → `.ts` (git mv + типизация), новый
  `src/config/options.ts`, возможные локальные декларации `src/types/*.d.ts`.
- `package.json`: devDependencies `@types/*`.
- `tsconfig.json`: `allowJs: false` (финальная задача звена).
- Поведение CLI не меняется: golden-набор зелёный после каждой доменной группы
  без регенерации эталонов; конфиг `.c4builder` потребителей (repo `arch`)
  не затронут.

## design

[Обзор](#C4-Builder)

## Context

После `ts-scaffold` исходники — честный ESM в доменной раскладке `src/`
(cli / core / config / util), компиляция `tsc → dist/` (Стойка 2:
`.ts`-импорты + `rewriteRelativeImportExtensions`), `strict` уже включён в
`tsconfig.json`, но действует только на `.ts`-файлы — которых ноль: все
16 модулей (~2600 строк) остались `.js` под `allowJs: true`. Golden-матрица
из трёх вариантов даёт поведенческую сетку; `typescript@5.9.3` в devDeps.

Изначальный план порта — четыре отдельных change'а по доменам. Пересмотрено:
база мала, страховка процесса не окупает накладные расходы четырёх циклов
propose→apply→archive. Порт — одним change, домены — группами задач.

## Goals / Non-Goals

**Goals:**
- 100% исходников `src/` — `.ts` под `strict`; `allowJs` выключен.
- Опорные типы конфига (`BuildOptions`, ключи `.c4builder`) в `src/config/`.
- Паритет поведения: golden зелёный после каждой доменной группы, без
  регенерации эталонов; рантайм-логика не правится.

**Non-Goals:**
- Дробление `core/build.ts` на scan/render/compose — следующий change
  (`build-split`).
- Рантайм-валидация конфига (`zod`), апгрейды зависимостей, TeaVM.
- Починка легаси-дефектов (заглушка `writeOnSameLine`, глотание ошибок
  `makeDirectory`, двухветочный вызов `joi.validate`) — типизируются как есть.

## Decisions

**Один change, домены — как порядок задач.** Группы: `config` → `util` →
`core` → `cli` → `index` → флип `allowJs: false`. После каждой группы —
golden; каждая группа — отдельный коммит (точка отката). Порядок — от
листьев графа импортов к корню: когда портируется потребитель, его
зависимости уже типизированы.

**Оптимистичный тип `BuildOptions` (поля обязательны).** `conf.get()` на
неполном `.c4builder` возвращает `undefined`, «честный» тип — все ~35 полей
`| undefined` — заставил бы расставить по `build.js` сотни проверок/`??`,
каждая — риск поведенческого дрейфа. Wizard и `--new --yes` гарантируют
полный конфиг на практике; тип фиксирует этот контракт, рантайм не трогаем
вообще. Честность на входе добавит звено `zod` (рантайм-валидация + сужение).
- *Альтернатива (отвергнута):* честный тип `Partial` — точнее, но превращает
  механический порт в аудит 880-строчного монолита.

**Типы конфига — в `src/config/options.ts`, объявляются первой группой.**
`getOptions()` живёт в `cli/dispatch` (портируется последним), но его
результат потребляет `build()` (портируется раньше). Объявляем тип в
`config/` сразу: `C4ConfigFile` (camelCase-ключи `.c4builder`, супертип
`defaultConfig`) и `BuildOptions` (SCREAMING_CASE-опции). Легаси-поля
(`LEGACY_PLANTUML_VERSION`, `LEGACY_PDF_KEYS`, `HAS_RUN`) типизируются как
есть с пометкой.

**Правило импортов в смеси `.ts`/`.js` на время порта.** Непортированные
`.js` продолжают импортировать `'./x.js'` — nodenext-резолюция TS подставляет
`x.ts` при компиляции, эмит не меняется. Следствие: переименование модуля
**не требует правок потребителей**, группы независимы. Портированные `.ts`
пишут импорты с `.ts` (Стойка 2). Финальный флип закрывает смесь.

**Типы зависимостей: точечно, с `skipLibCheck`.** `@types/node` обязателен
(первый же `.ts` с `node:fs` без него не соберётся). Для CJS-зависимостей
без встроенных типов — `@types/configstore`, `@types/inquirer@^8`,
`@types/figlet`, `@types/fs-extra`, `@types/express@^4`; свои типы несут
`commander`, `chalk@2`, `@resvg/resvg-js`, `node-watch`, `@terrastruct/d2`.
Несовпадение версии/формы — локальная декларация `src/types/<pkg>.d.ts`
(минимальная, по фактическому потреблению), не апгрейд пакета.

**Легаси типизируется по фактическому потреблению.** Если strict вскрывает
дефект (мёртвый параметр, недостижимая ветка), фиксируем сигнатуру «как
есть» (`_fn?: unknown`) или точечный `// biome-ignore`/`@ts-expect-error`
с причиной — но не меняем рантайм. Известные места: `writeOnSameLine`
(игнорирует `_fn`), `makeDirectory` (резолвится и при ошибке mkdir),
двухветочный `joi.validate` в wizard'е. Накопленные пометки — бэклог для
звена починки легаси.

## Risks / Trade-offs

- **[Оптимистичный тип врёт для рукописных неполных `.c4builder`]** → рантайм
  идентичен сегодняшнему (undefined течёт как falsy); враньё закроет звено
  `zod`. Тип — не новая гарантия, а документация текущего контракта.
- **[«Мелкие правки под компилятор» меняют поведение]** → правило: правка,
  меняющая рантайм, запрещена; сомнение → каст с комментарием. Контроль —
  golden после каждой группы + ревью диффа на «rename-only».
- **[@types/* не совпадёт со старой мажорной версией пакета]** →
  `skipLibCheck` уже стоит; крайний случай — локальный `d.ts` по фактическому
  API, зависимость не апгрейдится.
- **[880-строчный `build.ts` под strict даст лавину ошибок]** → тип
  `BuildOptions` оптимистичный (снимает основной класс `undefined`-ошибок);
  внутренние структуры (`tree`, элементы скана) типизируются локальными
  интерфейсами в том же файле — они станут границами модулей при
  `build-split`.

## Migration Plan

Порядок задач (golden зелёный после каждого пункта, каждый — коммит):
1. devDeps: `@types/node` + точечные `@types/*`; `npm run build` зелёный.
2. `config/`: `defaults.ts`, новый `options.ts` (`BuildOptions`, `C4ConfigFile`).
3. `util/`: `paths.ts`, `utils.ts`.
4. `core/`: `render/*` (jre, d2renderer, pngraster), `compose/docsify.template.ts`,
   `build.ts` (монолит, внутренние интерфейсы локально).
5. `cli/`: `commands/*`, `wizard/collect.ts`, `dispatch.ts` (типизирует
   `getOptions(): BuildOptions`), затем `index.ts`.
6. Флип: `allowJs: false`; проверка `find src -name '*.js'` пуст; `npm pack`
   санити на состав пакета.

Откат — по коммитам групп; change самодостаточен.

## Open Questions

- Нет: форма (один change), тип конфига (оптимистичный), место типов
  (`config/options.ts`) и судьба монолита (`build-split` следующим change'ом)
  согласованы в explore-сессии 2026-07-05.

## tasks

[Обзор](#C4-Builder)

## 1. Типы зависимостей

- [x] 1.1 devDeps: `@types/node`, `@types/configstore`, `@types/inquirer@^8`, `@types/figlet`, `@types/fs-extra`, `@types/express@^4`; проверить, чьи типы встроены (`commander`, `chalk@2`, `@resvg/resvg-js`, `node-watch`, `@terrastruct/d2`, `joi`); несовпадения — локальный `src/types/<pkg>.d.ts`; `npm run build` зелёный

## 2. config/

- [x] 2.1 Новый `src/config/options.ts`: `C4ConfigFile` (camelCase-ключи `.c4builder`) и `BuildOptions` (SCREAMING_CASE, оптимистичный — поля обязательны; легаси-поля с пометкой)
- [x] 2.2 `defaults.js → defaults.ts` (`defaultConfig` типизирован через `C4ConfigFile`); golden зелёный; коммит группы

## 3. util/

- [x] 3.1 `paths.js → paths.ts` (типизировать `packageJson` по фактическому потреблению)
- [x] 3.2 `utils.js → utils.ts` (сигнатуры как есть: `writeOnSameLine`, `makeDirectory` не чинить); golden зелёный; коммит группы

## 4. core/

- [x] 4.1 `render/jre.js → jre.ts`, `render/d2renderer.js → d2renderer.ts`, `render/pngraster.js → pngraster.ts`
- [x] 4.2 `compose/docsify.template.js → docsify.template.ts` (интерфейс параметров по вызову из build)
- [x] 4.3 `build.js → build.ts` монолитом: `build(options: BuildOptions, cacheConf)`, внутренние структуры (дерево скана и др.) — локальные интерфейсы; рантайм не менять; golden зелёный; коммит группы

## 5. cli/

- [x] 5.1 `commands/{help,list,new,site,jre}.js → .ts`
- [x] 5.2 `wizard/collect.js → collect.ts` (joi-обёртка `validate` как есть)
- [x] 5.3 `dispatch.js → dispatch.ts`: `getOptions(): BuildOptions`, типизировать заглушки `conf`/`cacheConf`
- [x] 5.4 `index.js → index.ts` (shebang сохраняется в эмите); golden зелёный; коммит группы

## 6. Финальный флип строгости

- [x] 6.1 `tsconfig.json`: `allowJs: false`; убедиться `find src -name '*.js'` пуст; `npm run build` + golden зелёные
- [x] 6.2 Санити состава пакета: `npm pack --dry-run` — `dist/` полон, лишнего нет; коммит

## specs

[Обзор](#C4-Builder)

- [build-pipeline](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-ts-port-full/specs/build-pipeline/build-pipeline)

## build-pipeline

[Обзор](#C4-Builder)

# build-pipeline — delta (ts-port-full)

## MODIFIED Requirements

### Requirement: Исходники на TypeScript и ESM

Исходный код CLI SHALL быть написан на TypeScript в модульной системе ESM.
Все модули под `src/` MUST иметь расширение `.ts`; `package.json` MUST
декларировать `"type": "module"`; модули MUST использовать `import`/`export`
(не `require`/`module.exports`) и лежать под `src/`, организованные по доменам
(`cli/`, `core/`, `config/`, `util/`). Компиляция MUST проходить в режиме
`strict` без ошибок.

#### Scenario: Модульный формат исходников
- **WHEN** просматривается любой модуль под `src/`
- **THEN** это `.ts`-файл с ESM-синтаксисом (`import`/`export`), а `package.json` содержит `"type": "module"`

#### Scenario: Строгая компиляция
- **WHEN** выполняется `npm run build`
- **THEN** `tsc` компилирует все модули `src/` в режиме `strict` без ошибок

#### Scenario: Ресурсы вне компиляции доступны из собранного кода
- **WHEN** собранный модуль обращается к вендорным ресурсам (`vendor/`) или шаблону (`template/`)
- **THEN** путь резолвится к корню пакета через `import.meta.url`, а не к каталогу внутри `dist/`, и рендер/скаффолд находят JAR, шрифты и шаблон

### Requirement: Компиляция tsc → dist/ без бандлера

Проект SHALL компилироваться `tsc` в каталог `dist/` без бандлера. `tsconfig.json`
MUST задавать `module`/`moduleResolution` `nodenext`, `outDir: dist`, `rootDir: src`.
Относительные импорты в исходниках MUST указывать расширение `.ts`
(`allowImportingTsExtensions`), а `tsc` MUST переписывать их в `.js` в эмите
(`rewriteRelativeImportExtensions`). `allowJs` MUST быть выключен: `.js`-модули
под `src/` не допускаются.

#### Scenario: Сборка порождает dist
- **WHEN** выполняется `npm run build`
- **THEN** `tsc` компилирует `src/**` в `dist/**` с расширениями `.js`, без бандлинга

#### Scenario: Расширения импортов переписываются
- **WHEN** исходный модуль содержит `import './render/diagram.ts'`
- **THEN** в соответствующем файле `dist/` импорт эмитится как `import './render/diagram.js'`

#### Scenario: Смесь .ts/.js запрещена
- **WHEN** под `src/` появляется `.js`-модуль
- **THEN** он не входит в компиляцию (`allowJs: false`) и сборка не может на него ссылаться

## 2026-07-07-build-split

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="5" max="5"></progress> 5/5 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-build-split/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-build-split/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-build-split/specs/specs)

# build-split — дробление монолита core/build.ts по фазам

## Why

`core/build.ts` — монолит на ~880 строк, в котором сплетены четыре фазы:
скан дерева исходников, рендер диаграмм, компоуз markdown/сайта и оркестрация.
Это блокирует дальнейшую эволюцию: рендер-фичи (TeaVM-бэкенд), точечные
юнит-тесты по фазам и осмысленные ревью. После `ts-port-full` база типизирована —
границы будущих модулей уже описаны локальными интерфейсами, дробление
становится механикой «перенос + экспорт» под защитой golden-матрицы.
Выполняется строго после `ts-port-full`.

## What Changes

- **Выделение фаз в модули** (по фактическому скелету монолита):
  - `core/scan/` — построение дерева исходников: `generateTree`,
    `getFolderName`, сворачивание инклюдов `foldIncludes`;
  - `core/render/` — пополняется `diagrams.ts`: `renderDiagram` (вызов java),
    `generateImages` (обход, чексуммы/кеш), `diagramOutputFormat` — рядом с
    уже живущими там `jre`, `d2renderer`, `pngraster`;
  - `core/compose/` — пополняется `markdown.ts`: `compileDocument`,
    `hasOwnH1`/`injectAfterFirstH1`, `generateMD`, `generateCompleteMD`,
    `generateWebMD` — рядом с `docsify.template.ts`.
- **`core/build.ts` становится оркестратором**: бэкап/восстановление `dist`,
  вызов фаз, прогресс — целевой размер порядка сотни строк.
- **Интерфейсы фаз — экспортируемые типы** (дерево скана, элемент диаграммы,
  колбэки прогресса) на границах модулей вместо локальных интерфейсов монолита.
- **Поведение CLI не меняется**: golden зелёный после каждого шага выделения,
  без регенерации эталонов.

Не входит: изменение логики фаз, рантайм-валидация конфига (`zod`), апгрейды
зависимостей, починка легаси-дефектов, TeaVM.

## Capabilities

### New Capabilities

Нет: наблюдаемое поведение CLI не меняется.

### Modified Capabilities

- `build-pipeline`: добавляется требование пофазной модульности ядра сборки —
  фазы scan/render/compose SHALL жить в отдельных модулях `core/<фаза>/`,
  `core/build.ts` SHALL остаться оркестратором без логики фаз.

## Impact

- Файлы: новые `src/core/scan/*.ts`, `src/core/render/diagrams.ts`,
  `src/core/compose/markdown.ts`; `src/core/build.ts` ужимается до оркестрации.
- Импорты потребителей `build()` (`cli/dispatch.ts`) не меняются.
- Поведение, конфиг `.c4builder`, состав пакета — без изменений; golden
  зелёный на каждом шаге.

## design

[Обзор](#C4-Builder)

## Context

После `ts-port-full` весь `src/` — строгий TypeScript, но `core/build.ts`
остаётся монолитом ~880 строк: скан (`generateTree`, `foldIncludes`), рендер
(`renderDiagram`, `generateImages`), компоуз (`compileDocument`, `generateMD`,
`generateCompleteMD`, `generateWebMD`) и оркестрация (`build`) — в одном файле
с общими замыканиями и локальными интерфейсами. Часть render- и compose-кода
уже выделена раньше (`render/{jre,d2renderer,pngraster}.ts`,
`compose/docsify.template.ts`) — монолит доразбирается в те же домены.
Golden-матрица фиксирует полный вывод трёх вариантов конфигурации.

## Goals / Non-Goals

**Goals:**
- Фазы scan / render / compose — отдельные модули со своими экспортируемыми
  типами границ; `build.ts` — только оркестрация (цель — порядка сотни строк).
- Перенос без изменения логики: golden зелёный после каждого шага выделения.
- Типы границ (дерево скана, элемент с диаграммами, колбэки прогресса) —
  публичные контракты фаз, на которые смогут опираться юнит-тесты и TeaVM-бэкенд.

**Non-Goals:**
- Изменение алгоритмов фаз, порядка обхода, формата вывода.
- Новые фичи рендера, `zod`, апгрейды зависимостей, починка легаси.
- Переработка уже выделенных модулей (`jre`, `d2renderer`, `pngraster`,
  `docsify.template`).

## Decisions

**Дробление по фактическим швам монолита, не по идеальной архитектуре.**
Модули повторяют существующие фазы: `scan/tree.ts` (генерация дерева +
`foldIncludes` + `getFolderName`), `render/diagrams.ts` (`renderDiagram`,
`generateImages`, `diagramOutputFormat`, `getMime`, `httpGet`),
`compose/markdown.ts` (`compileDocument`, `hasOwnH1`, `injectAfterFirstH1`,
три `generate*MD`). Никаких переименований функций и перестройки сигнатур
сверх необходимого для экспорта — дифф должен читаться как перенос.
- *Альтернатива (отвергнута):* заодно спроектировать «правильные» интерфейсы
  фаз (пайплайн, DI) — смешивает перенос с редизайном, ломает читаемость
  диффа; редизайн возможен позже поверх выделенных модулей.

**Типы границ живут в модуле-владельце.** Тип дерева скана — в `scan/tree.ts`,
тип задачи рендера — в `render/diagrams.ts`; compose импортирует тип дерева из
scan. Отдельного `core/types.ts` не заводим, пока нет типа с двумя владельцами.

**Порядок выделения — по потоку данных, шаг = коммит.** scan → render →
compose; после каждого шага монолит компилируется и golden зелёный. Оркестратор
ужимается естественно по мере выноса.

**Общие константы уходят к потребителям.** `FONTS_DIR`, `DEFAULT_FONT_NAME`,
`DIST_BACKUP_FOLDER_SUFFIX` и подобные переезжают в модуль единственного
потребителя; константа с двумя потребителями остаётся в `build.ts` до
появления явного владельца.

## Risks / Trade-offs

- **[Скрытая связность через замыкания монолита]** → выделение по одному шагу
  с компиляцией и golden после каждого; обнаруженная связность фиксируется
  явным параметром функции, не общим состоянием.
- **[Дифф «перенос» разъедется с «правкой»]** → правило rename-only: логика
  не меняется, форматирование не трогается; ревью сверяет тела функций.
- **[`httpGet`/серверный рендер — мёртвый или полумёртвый код уедет как есть]**
  → так и задумано: инвентаризация мёртвого кода — не этот change; переносим
  без ревизии.

## Migration Plan

1. `scan/tree.ts`: `generateTree` + `foldIncludes` + `getFolderName` + тип
   дерева; `build.ts` импортирует; golden; коммит.
2. `render/diagrams.ts`: `renderDiagram`, `generateImages`,
   `diagramOutputFormat`, `getMime`, `httpGet`; golden; коммит.
3. `compose/markdown.ts`: `compileDocument`, `hasOwnH1`,
   `injectAfterFirstH1`, `generateMD`, `generateCompleteMD`, `generateWebMD`;
   golden; коммит.
4. Ревизия остатка `build.ts` (оркестрация: бэкап dist, вызовы фаз, прогресс);
   константы — к владельцам; golden + `npm pack` санити; коммит.

Откат — по коммитам шагов; change выполняется строго после архивации
`ts-port-full`.

## Open Questions

- Нет: границы модулей (по фактическим швам), место типов (модуль-владелец)
  и порядок шагов согласованы в explore-сессии 2026-07-05.

## tasks

[Обзор](#C4-Builder)

## 1. Фаза scan

- [x] 1.1 `src/core/scan/tree.ts`: перенести `generateTree`, `foldIncludes`, `getFolderName` + экспортируемый тип дерева скана; `build.ts` импортирует; golden зелёный; коммит

## 2. Фаза render

- [x] 2.1 `src/core/render/diagrams.ts`: перенести `renderDiagram`, `generateImages`, `diagramOutputFormat`, `getMime`, `httpGet` + типы задач рендера/колбэка прогресса; golden зелёный; коммит

## 3. Фаза compose

- [x] 3.1 `src/core/compose/markdown.ts`: перенести `compileDocument`, `hasOwnH1`, `injectAfterFirstH1`, `generateMD`, `generateCompleteMD`, `generateWebMD` (тип дерева — импорт из scan); golden зелёный; коммит

## 4. Оркестратор

- [x] 4.1 Ревизия остатка `build.ts`: только оркестрация (бэкап/восстановление dist, вызовы фаз, прогресс); константы — к модулям-владельцам
- [x] 4.2 Финальная проверка: `npm run build`, golden, `npm pack --dry-run`; коммит

## specs

[Обзор](#C4-Builder)

- [build-pipeline](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-07-build-split/specs/build-pipeline/build-pipeline)

## build-pipeline

[Обзор](#C4-Builder)

# build-pipeline — delta (build-split)

## ADDED Requirements

### Requirement: Пофазная модульность ядра сборки

Ядро сборки SHALL быть организовано по фазам: скан дерева исходников
(`core/scan/`), рендер диаграмм (`core/render/`) и компоуз выводов
(`core/compose/`) MUST жить в отдельных модулях со своими экспортируемыми
типами границ. `core/build.ts` SHALL содержать только оркестрацию
(последовательность фаз, бэкап/восстановление выходного каталога, прогресс)
и MUST NOT содержать логику самих фаз.

#### Scenario: Фазы в отдельных модулях
- **WHEN** просматривается `src/core/`
- **THEN** построение дерева, рендер диаграмм и генерация markdown/сайта находятся в модулях `scan/`, `render/`, `compose/` соответственно, а не в `build.ts`

#### Scenario: Оркестратор без логики фаз
- **WHEN** просматривается `src/core/build.ts`
- **THEN** он импортирует фазы как модули и не содержит реализации скана, рендера или компоуза

#### Scenario: Дробление не меняет поведение
- **WHEN** golden-набор прогоняется после выделения фаз
- **THEN** результат совпадает с эталонами без их регенерации

## 2026-07-05-ts-scaffold

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="22" max="22"></progress> 22/22 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/specs/specs)

# ts-scaffold — каркас TypeScript/ESM: tsc → dist, доменная раскладка src/

## Why

Стартовое звено собственно порта на TypeScript (после `dev-toolchain`). Прежде
чем типизировать код по кластерам, нужен каркас, в который они лягут: конфиг
компилятора, сборка `tsc → dist/`, доменная раскладка `src/` и единый модульный
формат. Сейчас весь код — CommonJS (`module.exports`, 15 плоских файлов в корне,
`build.js` — монолит на 875 строк). Переход на ESM — глобальный рубильник
(`"type": "module"` в `package.json`), его нельзя делать по одному файлу, поэтому
он входит сюда как атомарный шаг. Само звено поведение CLI **не меняет**: golden
зелёный до и после.

## What Changes

- **Каркас компиляции (Стойка 2).** `tsconfig.json`: `module`/`moduleResolution`
  `nodenext`, `outDir: dist`, `rootDir: src`, `allowImportingTsExtensions` +
  `rewriteRelativeImportExtensions` — исходники пишутся с `.ts` в относительных
  импортах, `tsc` переписывает их в `.js` на выходе. Без бандлера. `allowJs: true`
  на время порта (пока часть модулей ещё `.js`).
- **Атомарный CJS → ESM флип.** `"type": "module"` в `package.json`; все файлы
  переводятся `require`/`module.exports` → `import`/`export` за один шаг
  (механически, golden зелёный). Интероп на время порта безопасен: `require(esm)`
  доступен с Node 20.19 (нижняя планка `engines`).
- **Доменная раскладка `src/`.** Плоский корень разъезжается по слоям:
  `cli/` (dispatch + `commands/` + `wizard/`), `core/` (`build.ts` +
  `scan/` + `render/` + `compose/`), `config/`, `util/`. `build.js` на этом
  шаге переезжает в `core/build.js` целиком — дробление монолита идёт в
  звеньях порта, не здесь.
- **Сборка и запуск из `dist/`.** npm-скрипт `build` (`tsc`); `bin`/`main` →
  `dist/index.js`; `files` → `dist/` (вместо перечня `cli*.js`); тест-хелпер и
  CI собирают `tsc` перед golden (тесты гоняют собранный CLI).
- **Docker.** Build-стадия на `node:24`, рантайм — как есть; итоговый образ
  запускает `dist/`.

Не входит (следующие звенья порта): переименование `.js → .ts` и типизация,
дробление `build.js` по фазам, починка известных легаси-дефектов
(implicit-глобал `responses` и мёртвая joi-валидация в `cli.collect.js`,
опечатка `EXECUTE_SCRIPT`), апгрейды зависимостей, `zod`, TeaVM-движок.

## Capabilities

### New Capabilities

- `build-pipeline`: как исходники пакета превращаются в поставляемый артефакт —
  язык и модульная система (TypeScript + ESM), шаг компиляции (`tsc → dist/`
  без бандлера, правило импортов Стойки 2), состав npm-пакета (`dist/` + `vendor/`
  + `template/`), точка входа (`bin` → `dist/index.js`), паритет поведения
  (golden зелёный).

### Modified Capabilities

- `ci-validation`: workflow собирает проект (`tsc`) перед прогоном тестов;
  ошибка компиляции — красный статус PR наравне с линтом и тестами.
- `dev-toolchain`: `files`-whitelist переезжает на `dist/` (в пакет больше не
  попадают корневые `cli*.js`); зона покрытия Biome включает `src/**/*.ts`.

## Impact

- Новые файлы: `tsconfig.json`, дерево `src/**` (переезд существующих модулей).
- Правки: `package.json` (`type`, `scripts.build`, `bin`/`main`, `files`,
  devDependency `typescript`), `.github/workflows/ci.yml` (шаг сборки),
  `Dockerfile` (build-стадия), `biome.json` (охват `src/`), тест-хелпер
  (`test/helpers.mjs` — запуск собранного CLI из `dist/`).
- Поведение CLI не меняется: golden-тест зелёный до и после каждого коммита звена.
- Потребители пакета (`arch` и др.): CLI запускается из `dist/`, конфиг
  `.c4builder` и вывод не затронуты.

## design

[Обзор](#C4-Builder)

## Context

Кодовая база — 100% CommonJS: 15 плоских `*.js` в корне, `build.js` — монолит
(875 строк: скан + рендер + компоуз + оркестрация). `dev-toolchain` уже дал Biome,
`files`-whitelist и `engines >=20.19`; golden-матрица из трёх fixture-конфигов
(`default`/`links-top`/`embed-png`) на пиновом managed-JRE фиксирует поведение.

Это звено ставит каркас порта: конфиг `tsc`, сборку в `dist/`, доменную раскладку
`src/` и единый модульный формат. Типизация и дробление монолита — в последующих
кластерах (`util+config` → `scan+render` → `compose` → `cli+wizard`).

## Goals / Non-Goals

**Goals:**
- Компиляция `tsc → dist/` без бандлера; исходники — честный TypeScript/ESM.
- Атомарный перевод всей базы CommonJS → ESM за один шаг.
- Доменная раскладка `src/` (cli / core / config / util), в которую лягут порты.
- Паритет поведения: golden-набор зелёный до и после; ноль правок логики CLI.

**Non-Goals:**
- Переименование `.js → .ts` и типизация (кластеры порта).
- Дробление `build.js` (переезжает в `core/build.js` целиком).
- Починка легаси-дефектов, апгрейды зависимостей, `zod`, TeaVM.

## Decisions

**Стойка 2: `rewriteRelativeImportExtensions`.** Пишем `import './x.ts'`, `tsc`
переписывает в `./x.js` на выходе — единственное исключение из правила «TS не
трогает пути импорта» (подтверждено дока́ми компилятора: `allowImportingTsExtensions`
разрешён с эмитом только при этом флаге). Исходник выглядит на 100% как TS.
- *Альтернативы:* Стойка 1 (plain `tsc`, `.js` в импортах) — работает, но `.js`
  в `.ts`-файле режет глаз; Стойка 3 (нативный TS-стрип Node, без сборки) —
  требует Node ≥22.18, рвёт `engines >=20.19` и совместимость потребителей на
  Node 20. Держим Node 20 → Стойка 2. Требует `typescript >= 5.7` (пин в devDeps).

**Доменная раскладка, глубокие слои.**
```
src/index.ts
src/cli/{dispatch, commands/*, wizard/*}
src/core/{build, scan/*, render/*, compose/*}
src/config/*  src/util/*
```
Плоский префиксный `src/` отвергнут — пользователь за глубокие домены.

**Атомарный ESM-флип внутри scaffold.** `"type": "module"` — глобальный рубильник:
как только он стоит, каждый оставшийся `.js` обязан быть ESM. Поэтому флип
`require`/`module.exports` → `import`/`export` делается разом по всей базе, не по
файлу. Интероп на время порта безопасен: `require(esm)` доступен с Node 20.19
(нижняя планка выбрана под это). CJS-зависимости (`chalk@2`, `inquirer@8`,
`fs-extra`, `configstore`, `open`) импортируются как default — ESM-интероп это
покрывает; они всё равно уходят в звене `deps`.

**Централизованный резолвер путей к ресурсам.** `vendor/` (JAR, шрифты, docsify),
`template/`, `package.json` лежат в корне пакета и **не компилируются** в `dist/`.
После переезда модулей в `dist/**` наивный `path.join(__dirname, 'vendor')`
сломается (укажет внутрь `dist/`). Решение: единый `src/util/paths.ts` вычисляет
корень пакета от `import.meta.url` и экспортирует `VENDOR_DIR`, `TEMPLATE_DIR`,
`packageJson`; все восемь текущих `__dirname`-обращений (`cli.new.js`,
`pngraster.js`, `build.js`) идут через него. Заодно централизует то, что сейчас
размазано. `require('./package.json')` → чтение через `createRequire`/`fs` там же.

**Scaffold механический; `build.js` целиком.** Дробление монолита — это дизайн и
типы, его место в кластере `scan+render`/`compose`. Здесь `build.js` только
переезжает в `core/build.js` (ещё `.js`, уже ESM). `allowJs: true` держит смесь
`.ts`/`.js` компилируемой на всём протяжении порта.

**Сборка и запуск из `dist/`.** `bin`/`main` → `dist/index.js`; npm-скрипт `build`
(`tsc`); golden гоняет собранный CLI — тест-хелпер и CI делают `tsc` перед тестами.
Shebang `#!/usr/bin/env node` сохраняется в `src/index.ts` (tsc переносит ведущий
shebang в эмит).

## Risks / Trade-offs

- **Пути к ресурсам после переезда в `dist/`** → централизованный `paths.ts`
  (см. выше); golden покрывает рендер (JAR+шрифты) и `new` (template), даёт
  сигнал сразу.
- **ESM-мины при флипе** (`__dirname`/`__filename`, `require(json)`, интероп
  CJS-депов) → перечислены поимённо выше; конверсия механическая, golden +
  ручной smoke `--help`/`--new` ловят регрессию.
- **Тесты теперь зависят от шага сборки** → `pretest`/CI-шаг `tsc`; забыли
  собрать — тест падает явно, не втихую на старом `dist/`.
- **`typescript` как новая devDependency + пин ≥5.7** → фиксируем версию, как
  Biome; фича `rewriteRelativeImportExtensions` стабильна с 5.7.

## Migration Plan

Порядок задач звена (golden зелёный после каждого блока):
1. `tsconfig.json` (Стойка 2, `allowJs`), devDependency `typescript`, скрипт `build`.
2. Атомарный CJS→ESM флип всех файлов + `paths.ts` (снимает `__dirname`/JSON) —
   ещё в корне, проверка golden.
3. Переезд файлов в `src/<домены>`, правка относительных импортов — golden.
4. `package.json` (`type`, `bin`/`main`/`files` → `dist/`), Docker build-стадия,
   охват Biome `src/`, CI-шаг сборки, тест-хелпер на `dist/` — golden + `npm pack`.

Откат — обратимо на уровне git до влития; звено самодостаточно.

## Open Questions

- Нет открытых развилок: форма, тулчейн (Стойка 2), процесс (4 кластера) и
  размещение ESM-флипа согласованы в explore-сессии 2026-07-05.

## tasks

[Обзор](#C4-Builder)

## 1. Каркас компиляции

- [x] 1.1 Добавить devDependency `typescript` (пин точной версии ≥5.7)
- [x] 1.2 Создать `tsconfig.json`: `module`/`moduleResolution` `nodenext`, `target es2022`, `rootDir: src`, `outDir: dist`, `allowImportingTsExtensions: true`, `rewriteRelativeImportExtensions: true`, `allowJs: true`, `strict: true`; `include: ["src"]`
- [x] 1.3 npm-скрипт `build` (`tsc`); добавить `dist/` в `.gitignore` и `.dockerignore`

## 2. Атомарный CJS → ESM флип (в корне, до переезда)

- [x] 2.1 Проставить `"type": "module"` в `package.json`
- [x] 2.2 Перевести все модули `require`/`module.exports` → `import`/`export` (единым проходом)
- [x] 2.3 Создать модуль резолва путей (`import.meta.url` → корень пакета): экспорт `VENDOR_DIR`, `TEMPLATE_DIR`, `packageJson`
- [x] 2.4 Заменить восемь `__dirname`-обращений (`cli.new.js`, `pngraster.js`, `build.js`) на импорт из модуля путей
- [x] 2.5 Заменить `require('./package.json')` в `cli.js` на чтение из модуля путей (`createRequire`/`fs`)
- [x] 2.6 `d2renderer`: сохранить ленивый `import()` для `@terrastruct/d2`, убрать CJS-обходной комментарий
- [x] 2.7 Golden зелёный + ручной smoke `--help` и `--new` (флип не изменил поведение)

## 3. Доменная раскладка src/

- [x] 3.1 Создать дерево `src/{cli/{commands,wizard},core/{scan,render,compose},config,util}` и переместить модули по слоям (`build.js` → `core/build.js` целиком, `index.js` → `src/index.js` с сохранением shebang)
- [x] 3.2 Поправить относительные импорты под новую вложенность
- [x] 3.3 Golden зелёный (переезд не изменил поведение)

## 4. Сборка, упаковка, CI, Docker

- [x] 4.1 `package.json`: `bin`/`main` → `dist/index.js`; `files` → `dist/`, `template/`, `vendor/`, README, license
- [x] 4.2 `biome.json`: включить охват `src/**/*.ts`, добавить `dist/` в ignore
- [x] 4.3 `.github/workflows/ci.yml`: шаг `npm run build` перед тестами в node-матрице
- [x] 4.4 Тест-хелпер `test/helpers.mjs`: запускать CLI из `dist/`; гарантировать сборку перед golden (`pretest`/CI-шаг)
- [x] 4.5 `Dockerfile`: build-стадия на `node:24`, запуск из `dist/`
- [x] 4.6 Golden зелёный на собранном из `dist/` CLI; `npm pack --dry-run` — в пакете `dist/`+`vendor/`+`template/`, нет `src/`/openspec/test

## 5. Валидация звена

- [x] 5.1 `npm run build` без ошибок, `npm run lint` зелёный, весь golden зелёный
- [x] 5.2 Smoke: `node dist/index.js --help` и `node dist/index.js --new --name demo -y`
- [x] 5.3 `openspec validate ts-scaffold --strict` проходит

## specs

[Обзор](#C4-Builder)

- [build-pipeline](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/specs/build-pipeline/build-pipeline)
- [ci-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/specs/ci-validation/ci-validation)
- [dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-ts-scaffold/specs/dev-toolchain/dev-toolchain)

## build-pipeline

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Исходники на TypeScript и ESM

Исходный код CLI SHALL быть написан на TypeScript в модульной системе ESM.
`package.json` MUST декларировать `"type": "module"`; исходные модули MUST
использовать `import`/`export` (не `require`/`module.exports`) и лежать под
`src/`, организованные по доменам (`cli/`, `core/`, `config/`, `util/`).

#### Scenario: Модульный формат исходников
- **WHEN** просматривается любой модуль под `src/`
- **THEN** он использует ESM-синтаксис (`import`/`export`), а `package.json` содержит `"type": "module"`

#### Scenario: Ресурсы вне компиляции доступны из собранного кода
- **WHEN** собранный модуль обращается к вендорным ресурсам (`vendor/`) или шаблону (`template/`)
- **THEN** путь резолвится к корню пакета через `import.meta.url`, а не к каталогу внутри `dist/`, и рендер/скаффолд находят JAR, шрифты и шаблон

### Requirement: Компиляция tsc → dist/ без бандлера

Проект SHALL компилироваться `tsc` в каталог `dist/` без бандлера. `tsconfig.json`
MUST задавать `module`/`moduleResolution` `nodenext`, `outDir: dist`, `rootDir: src`.
Относительные импорты в исходниках MUST указывать расширение `.ts`
(`allowImportingTsExtensions`), а `tsc` MUST переписывать их в `.js` в эмите
(`rewriteRelativeImportExtensions`). На время порта `allowJs` MUST быть включён,
чтобы смесь `.ts`/`.js` компилировалась.

#### Scenario: Сборка порождает dist
- **WHEN** выполняется `npm run build`
- **THEN** `tsc` компилирует `src/**` в `dist/**` с расширениями `.js`, без бандлинга

#### Scenario: Расширения импортов переписываются
- **WHEN** исходный модуль содержит `import './render/diagram.ts'`
- **THEN** в соответствующем файле `dist/` импорт эмитится как `import './render/diagram.js'`

### Requirement: CLI запускается из собранного dist/

Опубликованный и локально собранный CLI SHALL исполняться из `dist/`. Поля `bin`
и `main` в `package.json` MUST указывать на `dist/index.js`; точка входа MUST
сохранять shebang `#!/usr/bin/env node`.

#### Scenario: Запуск собранного CLI
- **WHEN** после `npm run build` выполняется `node dist/index.js --help`
- **THEN** CLI выводит справку (эквивалентно запуску до порта)

#### Scenario: bin установленного пакета указывает на dist
- **WHEN** пакет установлен и вызвана команда `c4builder`
- **THEN** запускается `dist/index.js`

### Requirement: Порт сохраняет наблюдаемое поведение

Переход на TypeScript/ESM MUST NOT менять наблюдаемое поведение CLI: вывод сборки
(сайт/markdown, диаграммы), формат конфига `.c4builder` и совместимость с
конфигом потребителя MUST оставаться прежними. Golden-набор MUST проходить без
регенерации эталонов.

#### Scenario: Golden-паритет
- **WHEN** golden-набор прогоняется на собранном из `dist/` CLI
- **THEN** результат совпадает с эталонами без их обновления

## ci-validation

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Проект компилируется перед тестами

CI workflow MUST компилировать проект (`tsc`) до прогона тестов на каждой ноде матрицы, так как тесты исполняют собранный CLI из `dist/`. Ошибка компиляции MUST приводить к красному статусу проверки PR наравне с падением тестов и линта.

#### Scenario: Сборка перед тестами
- **WHEN** выполняется job тестовой матрицы (Node 22/24)
- **THEN** среди шагов присутствует сборка (`npm run build` / `tsc`) перед запуском тестов, и тесты исполняют CLI из `dist/`

#### Scenario: Ошибка компиляции в PR
- **WHEN** в PR попадает код, не компилируемый `tsc`
- **THEN** job завершается с ненулевым кодом и PR получает failed-статус проверки

## dev-toolchain

[Обзор](#C4-Builder)

## MODIFIED Requirements

### Requirement: Единый линтер и форматтер
Репозиторий SHALL использовать Biome (пин точной версии в devDependencies) как единственный линтер и форматтер JS/TS/JSON-кода. Конфигурация `biome.json` MUST соответствовать существующему стилю кода (отступ 4 пробела, одинарные кавычки, точки с запятой, ширина строки ~110) и MUST покрывать исходники под `src/**/*.ts`, а линт MUST базироваться на наборе `recommended`; отключение правила или локальный `biome-ignore` MUST сопровождаться комментарием-причиной.

#### Scenario: Локальная проверка
- **WHEN** разработчик запускает `npm run lint` (или `npm run check`)
- **THEN** Biome проверяет линт и формат всех файлов вне ignore-зон (включая `src/**/*.ts`) и завершается ненулевым кодом при нарушениях

#### Scenario: Автоформатирование
- **WHEN** разработчик запускает `npm run format`
- **THEN** Biome приводит файлы к сконфигурированному стилю на месте

#### Scenario: Воспроизводимость версии
- **WHEN** линт/формат запускаются локально и в CI
- **THEN** используется одна и та же пинованная версия Biome и результат идентичен

### Requirement: Состав npm-пакета ограничен whitelist'ом
`package.json` MUST содержать `files`-whitelist, включающий только собранный код CLI (`dist/`), `template/`, `vendor/`, README и лицензию. Служебные директории и исходники (openspec/, docs/, test/, `src/`, CI-конфиги, Dockerfile, tsconfig) MUST NOT попадать в публикуемый пакет. Опубликованный пакет MUST оставаться работоспособным: `c4builder --help` и `c4builder new` с шаблоном и вендорными ресурсами работают из установленного пакета.

#### Scenario: Проверка состава пакета
- **WHEN** выполняется `npm pack --dry-run`
- **THEN** в списке файлов пакета присутствуют `dist/`, `template/`, `vendor/`, README и отсутствуют openspec/, docs/, test/, `src/`, Dockerfile

#### Scenario: Smoke-проверка установленного пакета
- **WHEN** пакет из tarball устанавливается в чистую директорию и запускается `c4builder --help` и неинтерактивный `c4builder --new --name demo -y`
- **THEN** команды завершаются успешно, проект создаётся из шаблона

## 2026-07-05-resvg-png

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="17" max="17"></progress> 17/17 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-resvg-png/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-resvg-png/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-resvg-png/specs/specs)

# PNG-вывод через растеризацию SVG (resvg)

> **Зависит от:** `plantuml-java-direct`, `d2-backend` (оба в архиве — предусловие выполнено).
> **Порядок:** независим от cleanup-ветки (remove-pdf / remove-plantuml-version / new-noninteractive).

## Why

`DIAGRAM_FORMAT=png` коллеги иногда используют, но после перехода на java-direct и
двухбэкендную схему PNG стал непоследовательным: PlantUML отдаёт PNG нативно (AWT,
`-tpng`), а D2 всегда рендерит SVG — при `png` D2-диаграммы молча остаются SVG.
Нативный PlantUML-PNG к тому же растеризуется средствами JVM (Java2D/AWT), чья
геометрия и сглаживание зависят от версии JRE и платформы — тот же источник
недетерминизма, из-за которого golden уже пришлось калибровать под CI (`ditaa.png`).

`@resvg/resvg-js` (Rust, prebuilt-бинарь, **без браузера**, ~120 мс/диаграмма) даёт
единый детерминированный растеризатор SVG→PNG. Оба движка уже умеют SVG (это их
формат рендера) — остаётся одна стадия растеризации поверх, одинаковая для PlantUML
и D2, со вшитым вендорным шрифтом (кириллица, повторяемые метрики).

## What Changes

- **PNG формируется растеризацией SVG, а не нативным движком.** Движки рендерят SVG;
  при `DIAGRAM_FORMAT=png` не-ditaa диаграммы прогоняются через resvg SVG→PNG.
  PlantUML перестаёт вызываться с `-tpng` для обычных диаграмм.
- **D2 начинает поддерживать `png`.** Раньше `.d2` при `png` оставались SVG — теперь
  их SVG так же растеризуется в PNG. Формат становится единообразным для обоих движков.
- **ditaa не затрагивается.** ditaa не имеет SVG-представления и остаётся нативным
  PlantUML-PNG (golden `ditaa.png` не меняется).
- **Детерминизм и кириллица.** resvg использует вендорный шрифт (`vendor/fonts/`),
  системные шрифты отключены; выход PNG повторяем на одной версии resvg.
- **`@resvg/resvg-js` — зависимость с ленивой загрузкой**, движок инициализируется
  только когда в проекте реально нужен PNG (есть не-ditaa диаграммы при `png`).

## Capabilities

### Modified Capabilities
- `diagram-rendering`: добавляется стадия растеризации SVG→PNG (resvg) для обоих
  движков при `DIAGRAM_FORMAT=png`; уточняется, что SVG — формат рендера движков, а
  PNG получается отдельной детерминированной стадией; ditaa остаётся нативным PNG.

## Impact

- `build.js`: в `generateImages` после рендера SVG (PlantUML/D2) — ветка растеризации
  в PNG через resvg для не-ditaa диаграмм; PlantUML для не-ditaa рендерится в `svg`,
  а не `-tpng`; ditaa-путь без изменений.
- Новый модуль растеризации (напр. `pngraster.js`) с ленивой загрузкой resvg и
  конфигом шрифта (`fontDirs: [vendor/fonts]`, `loadSystemFonts: false`).
- `package.json`: `@resvg/resvg-js` в зависимостях (native prebuilt-бинарь).
- Кэш чексумм: логика не меняется (ключ по контенту+инклюдам), но имя выхода уже
  учитывает формат (`diagramOutputFormat`) — PNG кэшируется как PNG.
- **Порядок в цепочке — строго после `plantuml-java-direct` и `d2-backend`**
  (оба в архиве/реализованы): resvg опирается на SVG-выход обоих движков и на
  вендорный шрифт из java-direct. Раньше этих изменений делать нельзя.
- **Не затрагивается**: golden-fixture (`diagramFormat=svg`), `ditaa.png`, спеки
  `regression-testing`/`ci-validation`.

## design

[Обзор](#C4-Builder)

## Context

Формат выхода диаграммы задаёт `diagramOutputFormat(diagram, options)`:
D2 → всегда `svg`, ditaa → всегда `png`, иначе → `DIAGRAM_FORMAT`. `renderDiagram`
зовёт `java ... -t${format} -pipe`, то есть PlantUML сейчас растеризует PNG сам
(AWT). D2 (`renderD2`) отдаёт только SVG. Итог: при `png` PlantUML даёт PNG, а D2 —
SVG (непоследовательно), и PlantUML-PNG недетерминирован по JVM/платформе.

Этот change идёт **строго после** `plantuml-java-direct` (java-direct + Smetana +
вендорный шрифт → детерминированный SVG) и `d2-backend` (D2→SVG со вшитыми шрифтами).
Оба уже в архиве. resvg — тонкая стадия поверх их SVG-выхода.

## Goals / Non-Goals

**Goals:**
- Единый детерминированный SVG→PNG для обоих движков без браузера.
- D2 начинает честно поддерживать `DIAGRAM_FORMAT=png`.
- Кириллица и повторяемость PNG за счёт вендорного шрифта.
- Ленивая загрузка растеризатора: SVG-проекты и «только ditaa» его не тянут.

**Non-Goals:**
- Трогать ditaa (остаётся нативный PlantUML-PNG; golden `ditaa.png` неизменен).
- Конфигурируемый DPI/масштаб PNG (стартуем с 1:1; при спросе — отдельная фича).
- Расширять основной golden-fixture на PNG (fixture остаётся svg; для PNG —
  отдельная проверка детерминизма, см. Open Questions).

## Decisions

### Единый растеризатор поверх SVG вместо нативного PNG
PlantUML для не-ditaa при `png` рендерится в **SVG** (`-tsvg`), затем resvg → PNG.
D2-SVG так же → PNG. Одна стадия, один растеризатор, одинаковый результат для обоих
движков и детерминизм лучше AWT.
*Альтернатива* — оставить нативный PlantUML `-tpng` и добавить SVG→PNG только для D2:
отвергнута — два разных PNG-рендера, D2 и PlantUML визуально расходятся, недетерминизм
AWT сохраняется.

### resvg-js, а не sharp/canvas/headless
`@resvg/resvg-js` — Rust + napi, prebuilt-бинари, без браузера и без системных
зависимостей, ~120 мс/диаграмма (замерено). Согласуется с линией «ноль внешних
зависимостей».
*Альтернатива* — puppeteer/headless (только что выпилили с PDF) или node-canvas
(нужен нативный toolchain/cairo): отвергнуты.

### Шрифт: vendor/fonts + loadSystemFonts:false
resvg должен рисовать текст сам. PlantUML-SVG ссылается на шрифт по имени
(`Liberation Sans`) — resvg обязан загрузить файл из `vendor/fonts/`. D2-SVG несёт
шрифт во вшитом `@font-face` (base64), но `loadSystemFonts:false` фиксируем всё равно,
чтобы исключить платформенный fallback. Конфиг: `font: { fontDirs: [FONTS_DIR],
defaultFontFamily: DEFAULT_FONT_NAME, loadSystemFonts: false }`.

### Ленивая загрузка и «нужен ли PNG вообще»
Растеризатор грузится (`require`) лениво в модуле `pngraster.js`, только если в дереве
есть хотя бы одна не-ditaa диаграмма при `DIAGRAM_FORMAT=png`. Отсутствие пакета в этот
момент — понятная ошибка с подсказкой (по образцу ленивого D2).

### Точка вклинивания в generateImages
В `generateImages` после получения буфера рендера: если целевой формат PNG и диаграмма
не ditaa — прогнать SVG-буфер через resvg перед `writeFile`. Для PlantUML это значит
рендерить `svg` внутри, а имя/формат выхода (`diagramOutputFormat` → `png`) и кэш
остаются как есть. ditaa-ветка (`isDitaa` → нативный `png`) не меняется.

## Risks / Trade-offs

- **PNG существующих png-проектов визуально изменится** (resvg vs AWT) → приемлемо и
  осознанно: детерминированнее и единообразнее; png — вторичный формат («коллеги
  иногда»). Отметить в change-логе.
- **Native prebuilt-бинарь в офлайн-корпсреде** (`@resvg/resvg-js-linux-x64-gnu`) →
  зеркало Artifactory npm должно отдавать нужный платформенный пакет; проверить, что
  ставится без сети после первого `npm ci`. Возможен musl/gnu-нюанс.
- **Детерминизм PNG завязан на версию resvg** (растровый выход может дрогнуть между
  версиями resvg, как `ditaa.png` между JRE) → пинуем версию resvg; PNG в golden — с
  оглядкой (см. Open Questions).
- **Забыли развести svg-рендер и png-выход для PlantUML** → тест: при `png` не-ditaa
  `.puml` даёт валидный PNG, ditaa — прежний байт-в-байт.

## Open Questions

- Покрывать ли PNG golden-эталоном? Вариант: отдельный мини-прогон с `png` +
  проверка «два прогона идентичны», без калибровки байтов под CI (или с пином resvg).
  Решить при написании теста.
- Дефолтный масштаб PNG: 1:1 к SVG-размеру против фикс-DPI. Стартуем с 1:1;
  конфигурируемость — вне объёма.

## tasks

[Обзор](#C4-Builder)

# Tasks: resvg-png

> Предусловие: change выполняется ТОЛЬКО после `plantuml-java-direct` и `d2-backend`
> (оба в архиве/реализованы). resvg опирается на их SVG-выход и вендорный шрифт.

## 1. Зависимость растеризатора

- [x] 1.1 Добавить `@resvg/resvg-js` в `dependencies`; зафиксировать (пин) версию
- [x] 1.2 Проверить установку prebuilt-бинаря в офлайн/корп-среде (Artifactory npm,
      linux-x64-gnu); задокументировать в README при необходимости

## 2. Модуль растеризации

- [x] 2.1 Создать `pngraster.js`: ленивый `require('@resvg/resvg-js')`, при отсутствии
      пакета — понятная ошибка с подсказкой установки
- [x] 2.2 Экспорт `rasterizeSvgToPng(svgBuffer)` с конфигом шрифта
      (`fontDirs: [vendor/fonts]`, `defaultFontFamily`, `loadSystemFonts: false`), масштаб 1:1
- [x] 2.3 Убедиться, что вход — валидный SVG обоих движков (PlantUML по имени шрифта,
      D2 со вшитым `@font-face`), кириллица отрисована

## 3. Встраивание в generateImages (build.js)

- [x] 3.1 Для PlantUML не-ditaa при `DIAGRAM_FORMAT=png` рендерить внутри `svg`
      (не `-tpng`), затем `rasterizeSvgToPng` перед `writeFile`; имя/формат выхода
      (`diagramOutputFormat` → png) и кэш не менять
- [x] 3.2 Для D2 при `png`: SVG-выход `renderD2` прогонять через `rasterizeSvgToPng`
- [x] 3.3 ditaa-ветку не трогать (нативный `png`, без растеризатора)
- [x] 3.4 Лениво инициализировать растеризатор только при наличии не-ditaa диаграмм
      и `png`; для svg/только-ditaa — не грузить

## 4. Кэш

- [x] 4.1 Проверить, что PNG кэшируется/восстанавливается как PNG (ключ по
      контенту+инклюдам, имя выхода уже учитывает формат) — регрессий нет

## 5. Верификация

- [x] 5.1 Прогон проекта с `DIAGRAM_FORMAT=png`: не-ditaa `.puml` и `.d2` дают
      валидные PNG, ссылки в md/site указывают на `.png`
- [x] 5.2 ditaa при `png` — нативный PNG, байт-в-байт как прежде (сверить с golden `ditaa.png`)
- [x] 5.3 Детерминизм: два прогона `png` дают идентичные PNG (при пине resvg)
- [x] 5.4 Кириллица в PNG корректна на машине без установленного Liberation Sans
- [x] 5.5 Основной golden (`diagramFormat=svg`) зелёный и неизменен
- [x] 5.6 (open) Решить и при необходимости добавить PNG-покрытие в тест
      (отдельный прогон/проверка идентичности), см. design Open Questions
- [x] 5.7 `openspec validate resvg-png --strict` проходит

## specs

[Обзор](#C4-Builder)

- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-resvg-png/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: PNG-вывод формируется растеризацией SVG
При `DIAGRAM_FORMAT=png` сборка SHALL получать PNG растеризацией SVG-выхода движка
(PlantUML или D2), а не нативным PNG-рендером. Не-ditaa диаграммы обоих движков
MUST рендериться в SVG и затем растеризоваться в PNG единым растеризатором. Растеризатор
MUST работать без браузера и без внешнего graphviz/dot. ditaa-диаграммы MUST оставаться
нативным PlantUML-PNG (у них нет SVG-представления) и MUST NOT проходить через растеризатор.

#### Scenario: PNG для PlantUML-диаграммы
- **WHEN** `DIAGRAM_FORMAT=png` и рендерится обычная (не-ditaa) `.puml`-диаграмма
- **THEN** PlantUML рендерит её в SVG, SVG растеризуется в PNG, выходной файл — `<имя>.png`

#### Scenario: PNG для D2-диаграммы
- **WHEN** `DIAGRAM_FORMAT=png` и рендерится `.d2`-диаграмма
- **THEN** D2 рендерит её в SVG, SVG растеризуется в PNG (раньше `.d2` при `png` оставались SVG)

#### Scenario: ditaa не растеризуется
- **WHEN** `DIAGRAM_FORMAT=png` и в проекте есть ditaa-диаграмма
- **THEN** ditaa рендерится нативным PlantUML-PNG без прохода через растеризатор, а её выход байт-в-байт совпадает с прежним

#### Scenario: SVG-формат не задействует растеризатор
- **WHEN** `DIAGRAM_FORMAT=svg`
- **THEN** диаграммы отдаются как SVG, растеризатор не вызывается и его зависимость не загружается

### Requirement: Детерминированная растеризация PNG с вендорным шрифтом
Растеризатор SVG→PNG SHALL использовать шрифт из состава репозитория (`vendor/fonts/`)
и MUST NOT подгружать системные шрифты, чтобы текст (включая кириллицу) рендерился
одинаково независимо от машины. Повторная растеризация одного SVG на одной версии
растеризатора MUST давать байт-в-байт идентичный PNG.

#### Scenario: Кириллица в PNG
- **WHEN** диаграмма с кириллическим текстом растеризуется в PNG
- **THEN** кириллица корректно отрисована шрифтом из `vendor/fonts/`, а не системным fallback

#### Scenario: Повторяемость PNG
- **WHEN** один и тот же SVG растеризуется дважды на одной машине
- **THEN** оба PNG байт-в-байт идентичны

### Requirement: Зависимость растеризатора загружается лениво
Пакет растеризатора SHALL загружаться только когда в проекте реально требуется PNG
(есть хотя бы одна не-ditaa диаграмма и `DIAGRAM_FORMAT=png`). При отсутствии пакета
в такой ситуации сборка MUST завершаться понятной ошибкой с подсказкой установки.

#### Scenario: PNG нужен, пакет не установлен
- **WHEN** `DIAGRAM_FORMAT=png`, есть не-ditaa диаграммы, но пакет растеризатора не установлен
- **THEN** сборка падает с понятным сообщением и подсказкой установки, а не с невнятной ошибкой модуля

#### Scenario: Растеризатор не нужен — не грузится
- **WHEN** формат SVG либо все диаграммы ditaa
- **THEN** пакет растеризатора не загружается

## MODIFIED Requirements

### Requirement: Второй бэкенд рендера выбирается по расширению
Сборка SHALL поддерживать `.d2`-диаграммы наравне с `.puml` и выбирать движок
рендера по расширению файла: `.puml` — PlantUML, `.d2` — D2. Добавление D2 MUST NOT
менять поведение существующих `.puml`-проектов; выходной файл диаграммы именуется по
имени исходного файла. Формат рендера обоих движков — SVG; при `DIAGRAM_FORMAT=png`
SVG растеризуется в PNG отдельной стадией (см. требование о PNG-выводе).

#### Scenario: Смешанное дерево .puml и .d2
- **WHEN** в дереве проекта присутствуют и `.puml`, и `.d2` файлы
- **THEN** `.puml` рендерятся PlantUML, `.d2` рендерятся D2, при формате по умолчанию
  (svg) оба дают SVG рядом с прочими выходами, ссылки в markdown работают для обоих

#### Scenario: Проект только из .puml не затронут
- **WHEN** в проекте нет ни одного `.d2`-файла
- **THEN** сборка и её выход идентичны прежнему поведению, а зависимость D2 не
  загружается

## 2026-07-05-remove-vscode-snippets

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="12" max="12"></progress> 12/12 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/tasks/tasks) · [README](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/README/README) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/specs/specs)

# Полное удаление VSCode-сниппетов из `c4builder --new`

> **Зависит от:** `new-noninteractive` (архив) — оно ввело флаги `--vscode`/`--no-vscode`,
> которые этот change убирает.
> **Порядок:** независим от остальной цепочки; после `new-noninteractive`.

## Why

`c4builder --new` опционально копирует файл автокомплит-сниппетов PlantUML
(`vendor/C4-PlantUML/C4.code-snippets`) в `.vscode/` создаваемого проекта. Ценность
фичи не подтверждается: это единственный потребитель вендорного каталога
`C4-PlantUML/`, а сами сниппеты доступны из редакторного расширения C4-PlantUML.
Фича добавляет промпт в `--new`, флаги `--vscode`/`--no-vscode` (введённые в
`new-noninteractive`) и мёртвый вендорный ассет. Дешевле убрать целиком.

## What Changes

- **VSCode-сниппеты убираются полностью.** `c4builder --new` больше не предлагает их
  скопировать — ни промптом, ни флагом — и не создаёт каталог `.vscode`.
- **Интерактивный `--new` схлопывается до одного вопроса** — имени проекта; при
  `--name` вопросов не остаётся вовсе.
- **Флаги `--vscode` / `--no-vscode` удаляются** (введены в `new-noninteractive`),
  вместе с механизмом `vscodeExplicit`. Остальные флаги `--new` (`--name`, `-y/--yes`)
  и headless-режим не затрагиваются.
- **Вендорный каталог `vendor/C4-PlantUML/` удаляется целиком** — его единственный
  файл `C4.code-snippets` был единственным потребителем удаляемой фичи (stdlib-инклюды
  `<C4/...>` в диаграммах резолвит сам PlantUML-jar, не этот каталог).
- **README не трогаем**: упоминание стороннего плагина `vscode-plantuml` (вьюер
  диаграмм) — не про эту фичу, остаётся.

## Capabilities

### Modified Capabilities
- `project-scaffold`: из требования о флагах `--new` уходят `--vscode`/`--no-vscode`
  и VSCode-сниппеты; фиксируется, что `--new` не создаёт `.vscode` и интерактивно
  спрашивает только имя.

## Impact

- `cli.new.js`: удаляется решение `isVSCode` (промпт/флаг) и copy-шаг сниппетов в
  `.vscode`; интерактивный `--new` спрашивает только имя; логика `cmdNewProject`
  упрощается (без `vscode`/`vscodeExplicit`).
- `cli.js`: удаляются опции `--vscode`/`--no-vscode` и вычисление `vscodeExplicit`.
- `vendor/C4-PlantUML/`: удаляется каталог (единственный файл — сниппеты).
- **Не затрагивается**: `--name`, `-y/--yes`, `defaultConfig`, headless-запись
  конфига, golden/CI, содержимое шаблона, README.
- **Сцепка с `new-noninteractive`** (архив): тот change ввёл `--vscode`/`--no-vscode`;
  здесь они убираются — требование `project-scaffold` о флагах модифицируется.

## design

[Обзор](#C4-Builder)

## Context

`c4builder --new` (`cmdNewProject`) после ввода имени спрашивает «Include the VSCode
autocomplete?» и при согласии копирует `vendor/C4-PlantUML/C4.code-snippets` в
`<project>/.vscode/C4.code-snippets`. `new-noninteractive` добавил флаги
`--vscode`/`--no-vscode` и `vscodeExplicit` (различить явный флаг от дефолта), чтобы
пропускать этот промпт. Каталог `vendor/C4-PlantUML/` содержит ровно один файл — эти
сниппеты; больше его никто не читает.

## Goals / Non-Goals

**Goals:**
- Убрать фичу VSCode-сниппетов целиком: промпт, флаги, copy-шаг, вендорный ассет.
- Интерактивный `--new` — только вопрос имени.
- Не задеть `--name`, `-y/--yes`, `defaultConfig`, headless-режим.

**Non-Goals:**
- Убирать упоминание стороннего `vscode-plantuml` из README (это про вьюер, не про фичу).
- Трогать шаблон, golden/CI, пути сборки.

## Decisions

### Убираем фичу целиком, не прячем за дефолтом
Единственный потребитель ассета, ценность не подтверждена — удаляем промпт, флаги и
copy-шаг, а не оставляем «выключенным по умолчанию». Меньше поверхности.
*Альтернатива* — оставить флаг `--vscode` выключенным по умолчанию: отвергнута,
мёртвый код и ассет ради неиспользуемой опции.

### Вендорный каталог `C4-PlantUML/` удаляем целиком
В нём только `C4.code-snippets`, и его читал лишь copy-шаг. Stdlib-инклюды `<C4/...>`
в диаграммах резолвит сам PlantUML-jar (проверено на golden), не этот каталог —
удаление безопасно.
*Альтернатива* — оставить файл «на всякий»: отвергнута, мёртвый груз в пакете.

### Интерактивный `--new` — только имя
После снятия VSCode-вопроса в интерактиве остаётся единственный промпт — имя проекта
(с прежней валидацией и ре-промптом). С `--name` вопросов нет. `--yes`/headless
не меняются.

### README-упоминание vscode-plantuml оставляем
Строка про плагин `vscode-plantuml` — совет по стороннему вьюеру `.puml`, не про
scaffold-фичу c4builder. Вне объёма.

## Risks / Trade-offs

- **Пользователи, полагавшиеся на авто-сниппеты** → сниппеты доступны из расширения
  C4-PlantUML в редакторе; c4builder перестаёт их навязывать. Отметить в change-логе.
- **Ветка `jre-resolver` держала свою копию `cli.new.js`** → консолидирована в
  phoenix, отдельного расхождения больше нет.

## tasks

[Обзор](#C4-Builder)

# Tasks: remove-vscode-snippets

> Зависит от `new-noninteractive` (архив): убирает введённые там флаги `--vscode`/`--no-vscode`.

## 1. CLI-флаги (cli.js)

- [x] 1.1 Удалить опции `--vscode` и `--no-vscode`
- [x] 1.2 Удалить вычисление `vscodeExplicit` и его проброс; `cmdNewProject` вызывается только с `opts`

## 2. Создание проекта (cli.new.js)

- [x] 2.1 Удалить решение `isVSCode` (промпт «Include the VSCode autocomplete?» и ветку флага)
- [x] 2.2 Удалить copy-шаг сниппетов в `.vscode/` (`if (isVSCode) { … C4.code-snippets … }`)
- [x] 2.3 Интерактивный `--new` оставляет единственный промпт — имя (валидация/ре-промпт как есть)
- [x] 2.4 Упростить логику `cmdNewProject` (без `opts.vscode`/`vscodeExplicit`)

## 3. Вендорный ассет

- [x] 3.1 Удалить каталог `vendor/C4-PlantUML/` целиком (единственный файл — сниппеты)

## 4. Верификация

- [x] 4.1 `grep -rniE "vscode|code-snippets" *.js` — не осталось живых ссылок (кроме source-attribution в utils.js)
- [x] 4.2 `c4builder --new --name demo` → проект без каталога `.vscode`, вопросов нет; `--new` без `--name` → спрашивает только имя
- [x] 4.3 `c4builder --new --yes --name demo` → как прежде, без `.vscode`
- [x] 4.4 Golden (`diagramFormat=svg`) неизменный от change: результат идентичен до/после правок. Тест сейчас red на `class.svg` (дрейф glyph-рендера PlantUML/шрифта) — воспроизводится на чистом HEAD без этих правок, к change отношения не имеет.
- [x] 4.5 `openspec validate remove-vscode-snippets --strict` проходит

## README

[Обзор](#C4-Builder)

# remove-vscode-snippets

Полное удаление VSCode-сниппетов из c4builder --new

## specs

[Обзор](#C4-Builder)

- [project-scaffold](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-vscode-snippets/specs/project-scaffold/project-scaffold)

## project-scaffold

[Обзор](#C4-Builder)

## MODIFIED Requirements

### Requirement: Флаги команды создания проекта
Команда `c4builder --new` SHALL принимать имя проекта через флаг `--name <name>`;
переданное значение MUST подставляться вместо интерактивного вопроса об имени.
Создание проекта MUST NOT предлагать VSCode-сниппеты — ни промптом, ни флагом — и
MUST NOT создавать каталог `.vscode` в проекте.

#### Scenario: Флаг имени заменяет промпт
- **WHEN** `c4builder --new --name demo` без `--yes`
- **THEN** вопрос об имени не задаётся, а VSCode-сниппеты не предлагаются

#### Scenario: Интерактивное создание спрашивает только имя
- **WHEN** `c4builder --new` без `--name` и без `--yes`
- **THEN** задаётся единственный вопрос — имя проекта; вопрос о VSCode-сниппетах не задаётся

#### Scenario: VSCode-каталог не создаётся
- **WHEN** проект создан через `c4builder --new` любым способом
- **THEN** каталог `.vscode` и файл сниппетов в проекте отсутствуют

## 2026-07-05-remove-plantuml-version

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="17" max="17"></progress> 17/17 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-plantuml-version/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-plantuml-version/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-plantuml-version/specs/specs)

# Удаление старых JAR и выбора версии PlantUML

> **Зависит от:** — (независимый cleanup; можно параллельно с `remove-pdf`).
> **Порядок:** до `new-noninteractive` (убирает флаг `--plantuml-version`, который тот не вводит).

## Why

В `vendor/` лежат 6 PlantUML-JAR (67 МБ), но актуален лишь один — `plantuml-1.2025.2.jar`
(21.7 МБ, `isLatest`). Пять старых версий существовали ради совместимости с онлайн-сервером
PlantUML (разные кодировки); после перехода на локальный java-direct рендер этот смысл
исчез. `PLANTUML_VERSION` тянется через утилиты, CLI, оба wizard'а и вывод — лишняя
поверхность и +45 МБ в пакете. Плейсхолдер `{{plantumlVersion}}` в шаблоне уже вычищен
(template-offline), а его подстановка в `cli.new.js` работает вхолостую.

## What Changes

- **Оставляем один вендорный JAR** (`plantuml-1.2025.2.jar`), удаляем пять старых:
  vendor 67 МБ → ~21 МБ.
- **Убираем концепцию версии**: массив `plantumlVersions` в `utils.js` → одна константа
  единственного JAR; в `build.js` резолв версии заменяется на прямой путь к нему.
- **Убираем `PLANTUML_VERSION`-опцию и промпты** выбора версии в `cli.new.js` и
  `cli.collect.js`, warning про несовместимость с онлайн-сервером, warning про обновление
  C4-PlantUML include URL, строку версии в `cli.list.js`.
- **Совместимость легаси-конфига.** `plantumlVersion` в существующем `.c4builder`
  игнорируется — всегда используется единственный JAR. Если ключ пинует конкретную (не
  `latest` и не текущую) версию, сборка печатает **однократное предупреждение**, что выбор
  версии удалён, и продолжается; конфиг не мутируется. На `latest`/текущей/отсутствии — тихо.
- Убираем мёртвую подстановку `{{plantumlVersion}}` в `cli.new.js`.

## Capabilities

### Modified Capabilities
- `diagram-rendering`: фиксируется единственный вендорный PlantUML-JAR (без выбора версии)
  и обработка легаси-ключа `plantumlVersion` (игнор + предупреждение на устаревшем пине).

## Impact

- `utils.js`: `plantumlVersions[6]` → константа единственного JAR (или `{version, jar}`).
- `build.js`: резолв `PLANTUML_VERSION`→JAR (стр. 263-265) заменяется прямым путём;
  импорт `plantumlVersions` убирается.
- `cli.js`: убирается опция `PLANTUML_VERSION`.
- `cli.new.js`: промпт версии, latest-warning, мёртвый `{{plantumlVersion}}`-replace,
  `conf.set('plantumlVersion')`, импорт `plantumlVersions`.
- `cli.collect.js`: промпт версии (стр. 238-281), warning про include URL, импорт.
- `cli.list.js`: строка вывода версии.
- `vendor/`: удаление 5 JAR.
- **Совместимость `arch`** гарантирована: его `.c4builder` пинует `plantumlVersion: "latest"`
  (+`generateLocalImages:true`, `svg`) → тот же JAR, предупреждение не срабатывает.
- **Golden не трогаем**: fixture пинует `1.2025.2` = оставляемый JAR → рендер идентичен.
- **Сцепка с `new-noninteractive`**: тот change добавляет флаг `--plantuml-version`; при
  заходе этого change флаг теряет смысл — реконсайл (см. design), рекомендуется этот раньше.
- **Вне объёма**: онлайн-сервер `PLANTUML_SERVER_URL` (родственная чистка из плана,
  отдельный change; `arch` им не пользуется).

## design

[Обзор](#C4-Builder)

## Context

`plantumlVersions` (`utils.js`) — массив из 6 версий, `isLatest` только у `1.2025.2`.
`build.js:263-265` резолвит JAR по `options.PLANTUML_VERSION` (`find` по версии, ветка
`latest`→isLatest, иначе throw). Версию спрашивают оба wizard'а (`cli.new.js`,
`cli.collect.js`) и показывает `cli.list.js`. Плейсхолдер `{{plantumlVersion}}` в шаблоне
уже удалён (template-offline), но `cli.new.js` всё ещё делает его подстановку вхолостую.

Шесть версий существовали ради совместимости с онлайн-сервером PlantUML (метка
«latest — compatible with plantuml online server», warning в `cli.new.js`). С локальным
java-direct рендером (Smetana, вендорный шрифт) выбор версии не нужен.

Главный потребитель `arch` пинует `plantumlVersion: "latest"` → резолвится в оставляемый
JAR; совместимость сохраняется при любом раскладе.

## Goals / Non-Goals

**Goals:**
- Один вендорный JAR (vendor 67 → ~21 МБ), удалить 5 старых.
- Убрать концепцию версии из утилит, CLI, обоих wizard'ов и вывода.
- Легаси `plantumlVersion` не ломает сборку: игнор + однократный warn на устаревшем пине.
- Golden неизменен (тот же JAR), конфиг не мутируется.

**Non-Goals:**
- Онлайн-сервер `PLANTUML_SERVER_URL` — отдельная чистка (в плане), здесь не трогаем.
- Обновление вендорного JAR на новую версию PlantUML.
- Автоправка `.c4builder` (только предупреждение).

## Decisions

### Один JAR как константа, без резолвинга версии
`plantumlVersions` заменяется единственной константой (напр. `VENDORED_JAR = { version:
'1.2025.2', jar: 'plantuml-1.2025.2.jar' }`). `build.js` берёт путь напрямую, ветка
`find/throw` уходит. Одна точка правды для имени JAR.
*Альтернатива* — оставить массив из одной записи ради «расширяемости»: отвергнута, версия
больше не пользовательский выбор.

### Легаси-ключ: игнор + warn на устаревшем пине
Всегда используется вендорный JAR. Предупреждение печатается, только если `plantumlVersion`
задан конкретной версией, отличной от `latest` и от версии вендорного JAR (т.е. реально
пинует удалённую) — чтобы `arch` («latest») и пин текущей версии молчали. Дом предупреждения
— начало рендера (`generateImages`), где раньше резолвилась версия.
*Альтернатива* — hard-fail на неизвестной версии (текущее поведение `throw`): отвергнута,
ломает чужие конфиги со старым пином.

### Мёртвую подстановку `{{plantumlVersion}}` удалить
После template-offline в шаблоне плейсхолдера нет; `.replace(...)` в `cli.new.js` — мёртвый
код, убираем вместе с версией.

### Fixture чистим от `plantumlVersion`
`test/fixture.c4builder.json` пинует `1.2025.2`; после удаления версии поле — безвредный
no-op. Убираем его: absent-ключ → тишина (без warn), рендер тем же вендорным JAR → golden
байт-в-байт неизменен. Дохлое поле в каноничной фикстуре не держим.

## Risks / Trade-offs

- **Чужой конфиг с пином удалённой версии** → не падает: игнор + понятный однократный warn.
- **Реконсайл с `new-noninteractive`**: тот change добавляет `--plantuml-version`. Если он
  заходит первым — здесь убрать флаг и его требование из `project-scaffold`; если этот
  первым — `new-noninteractive` не добавляет флаг вовсе (рекомендуется). Оформить как
  явную зависимость при планировании порядка.
- **Golden**: fixture пинует `1.2025.2` = вендорный JAR → рендер и эталон не меняются;
  `plantumlVersion` в fixture становится no-op (можно оставить или убрать косметически).

## Open Questions

- Нет открытых вопросов. Fixture-поле `plantumlVersion` решено убрать (см. Decisions):
  absent-ключ → тишина, тот же вендорный JAR → golden неизменен.

## tasks

[Обзор](#C4-Builder)

# Tasks: remove-plantuml-version

> Реконсайл: согласовать с `new-noninteractive` (флаг `--plantuml-version`). Рекомендуется
> этот change раньше — тогда new-noninteractive не добавляет флаг версии.

## 1. Вендорный JAR

- [x] 1.1 Удалить 5 старых JAR из `vendor/`, оставить `plantuml-1.2025.2.jar`
- [x] 1.2 Проверить размер vendor (~21 МБ) и что в пакет попадает только один JAR

## 2. utils.js и build.js

- [x] 2.1 Заменить `plantumlVersions[6]` на единственную константу JAR (version+jar)
- [x] 2.2 `build.js`: заменить резолв `PLANTUML_VERSION`→JAR (стр. 263-265) прямым путём;
      убрать импорт `plantumlVersions`

## 3. CLI: опция и вывод

- [x] 3.1 `cli.js`: убрать опцию `PLANTUML_VERSION` из `getOptions`
- [x] 3.2 `cli.list.js`: убрать строку вывода версии

## 4. Wizard'ы

- [x] 4.1 `cli.new.js`: убрать промпт версии, latest-warning, `conf.set('plantumlVersion')`,
      импорт `plantumlVersions`, мёртвый `{{plantumlVersion}}`-replace (стр. 54, 180)
- [x] 4.2 `cli.collect.js`: убрать промпт версии и warning про C4-PlantUML include URL
      (стр. 238-281), импорт `plantumlVersions`

## 5. Легаси-конфиг

- [x] 5.1 В начале рендера (`generateImages`) собрать `plantumlVersion` из конфига;
      если задан конкретной версией ≠ `latest` и ≠ версии вендорного JAR — однократный warn
- [x] 5.2 На `latest`/текущей/отсутствии — тихо; сборка всегда единственным JAR
- [x] 5.3 Убедиться, что конфиг не мутируется и сборка не падает из-за ключа

## 6. Fixture и верификация

- [x] 6.0 Убрать поле `plantumlVersion` из `test/fixture.c4builder.json` (no-op после удаления)
- [x] 6.1 Сборка проекта с `plantumlVersion: "latest"` (как `arch`) → без warn, рендер ок
- [x] 6.2 Сборка с `plantumlVersion: "1.2021.7"` → однократный warn, exit 0, конфиг не изменён
- [x] 6.3 Golden (`diagramFormat=svg`, fixture без версии) зелёный и неизменный — тот же JAR
- [x] 6.4 `grep -rniE "plantumlVersions|PLANTUML_VERSION|\{\{plantumlVersion\}\}"` — не
      осталось живых ссылок (кроме осознанной обработки легаси-ключа)
- [x] 6.5 `openspec validate remove-plantuml-version --strict` проходит

## specs

[Обзор](#C4-Builder)

- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-plantuml-version/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Единственный вендорный PlantUML JAR
Репозиторий SHALL поставлять ровно один PlantUML-JAR, и сборка MUST рендерить
PlantUML-диаграммы именно им, без выбора версии. Механизм выбора версии PlantUML
(список версий, опция и промпты) MUST отсутствовать.

#### Scenario: Рендер единственным JAR
- **WHEN** выполняется сборка PlantUML-диаграмм
- **THEN** используется единственный вендорный JAR, а какой-либо выбор версии не производится

#### Scenario: Нет промпта версии
- **WHEN** запускается создание проекта или мастер настройки
- **THEN** вопрос о версии PlantUML не задаётся

### Requirement: Легаси-ключ версии в конфиге игнорируется
Ключ `plantumlVersion` в существующем `.c4builder` SHALL игнорироваться: сборка всегда
использует единственный вендорный JAR. Если ключ задан конкретной версией, отличной от
`latest` и от версии вендорного JAR, сборка MUST напечатать однократное предупреждение,
что выбор версии удалён и используется вендорный JAR (ключ можно убрать), и продолжиться.
На значении `latest`, на версии вендорного JAR или при отсутствии ключа предупреждение
MUST NOT печататься. Сборка MUST NOT падать из-за этого ключа и MUST NOT изменять конфиг.

#### Scenario: Пин устаревшей версии
- **WHEN** в `.c4builder` `plantumlVersion` пинует удалённую версию (напр. `1.2021.7`)
- **THEN** печатается однократное предупреждение, сборка идёт единственным JAR, exit 0, конфиг не изменён

#### Scenario: latest или текущая версия — тихо
- **WHEN** `plantumlVersion` равен `latest`, версии вендорного JAR либо отсутствует
- **THEN** предупреждение не печатается, сборка идёт единственным JAR

## 2026-07-05-remove-pdf

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="24" max="24"></progress> 24/24 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-pdf/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-pdf/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-pdf/specs/specs)

# Удаление PDF-вывода

> **Зависит от:** — (независимый cleanup; можно параллельно с `remove-plantuml-version`).
> **Порядок:** до `new-noninteractive`.

## Why

PDF-вывод в c4builder держится на `md-to-pdf`, а тот тянет headless-браузер
(puppeteer/Chromium) — тяжёлую бинарную зависимость, несовместимую с линией
модернизации «ноль внешних зависимостей, офлайн, без браузера». При этом сам
формат перестал быть востребованным: документация потребляется как сайт/markdown
(в т.ч. AI-агентами), PDF-выходы не используются. Дешевле убрать целиком, чем
тащить Chromium через TS-порт и корпоративную офлайн-сборку.

## What Changes

- **PDF-вывод удаляется полностью** (`generatePDF` и `generateCompletePDF`).
  **BREAKING** для тех, кто ещё генерирует PDF: этот тип вывода больше недоступен.
- **Зависимость `md-to-pdf` (и транзитивный puppeteer/Chromium) выкидывается** из
  `package.json`; удаляется дефолтный стиль `pdf.css` и опция `pdfCss`.
- **Совместимость легаси-конфига без падений.** При truthy `generatePDF` /
  `generateCompletePDF` в существующем `.c4builder` сборка **не падает**: печатает
  предупреждение со списком **только реально присутствующих truthy PDF-ключей** и
  подсказкой удалить их вручную, затем собирает остальные выходы (md/website) и
  завершается с кодом 0. На `false`/отсутствующих ключах — тишина. Конфиг при этом
  **не мутируется** (файл в git не «дёргается»).
- **Wizard больше не предлагает PDF.** Из чекбокса форматов уходят оба PDF-пункта,
  исчезает вопрос про `pdfCss`; PDF-ключи убираются из логики «спросить ли формат»
  (`undefined`-гейт), чтобы конфиг без PDF-ключей не ре-триггерил промпт.
- **Docs/list очищаются** от PDF-описаний и строк вывода конфигурации.

## Capabilities

### New Capabilities
- `output-formats`: какие типы вывода поддерживает сборка (multiple-md,
  complete-md, website) и как обрабатывается легаси-конфиг с удалённым PDF-выводом
  (предупреждение без падения, без мутации конфига).

### Modified Capabilities
<!-- нет: regression-testing и ci-validation уже написаны «без PDF»,
     их требования не меняются -->

## Impact

- `build.js`: удаляются `generatePDF()`, `generateCompletePDF()` и `require('md-to-pdf')`;
  оркестрация PDF заменяется веткой-предупреждением; из gate'ов создания папок и
  копирования файлов убирается `|| GENERATE_PDF`.
- `cli.js`: убираются опции `GENERATE_PDF`, `GENERATE_COMPLETE_PDF_FILE`, `PDF_CSS`
  и упоминание PDF в предупреждении watch-режима.
- `cli.collect.js`: PDF-пункты чекбокса, `undefined`-гейт и блок `pdfCss`.
- `cli.help.js` / `cli.list.js`: блоки, описывающие PDF.
- `package.json`: удаляется зависимость `md-to-pdf`; из `description`/`keywords`
  убирается PDF.
- Файл `pdf.css` удаляется.
- **Не затрагивается**: golden-fixture (`test/fixture.c4builder.json` уже с
  `generatePDF: false`, `.pdf` в эталоне нет), спеки `regression-testing` и
  `ci-validation` (уже сформулированы «без PDF»). Golden-эталон не перегенерируется.
- Место в цепочке: следует за `golden-test-ci`, предшествует TS-порту (меньше кода
  тащить в TypeScript).

## design

[Обзор](#C4-Builder)

## Context

PDF-вывод реализован через `md-to-pdf` (обёртка над puppeteer/Chromium). Он
пронизывает пять слоёв: зависимости (`md-to-pdf`, `pdf.css`), рендер в `build.js`
(`generatePDF`, `generateCompletePDF`, `require('md-to-pdf')`), gate'ы создания
папок/копирования файлов (`|| GENERATE_PDF`), конфиг/wizard (три опции + промпты)
и docs/list. Требования зафиксированы в спеке `output-formats`; здесь — как
хирургически вырезать PDF, не задев остальные выходы, и где живёт предупреждение
для легаси-конфига.

Главный потребитель — репо `arch` (совместимость `.c4builder` обязательна).
Golden-fixture уже собран с `generatePDF: false` / `generateCompletePDF: false`,
`.pdf` в эталоне нет — удаление не должно менять golden-выход.

## Goals / Non-Goals

**Goals:**
- Полностью убрать PDF-код и зависимость `md-to-pdf`/Chromium.
- Легаси-конфиг с truthy PDF — не падает: понятное предупреждение, exit 0.
- Не мутировать `.c4builder` (файл не «дёргается» в git).
- Golden-эталон не перегенерируется (удаление не меняет выход fixture).

**Non-Goals:**
- Миграция существующих PDF в другой формат (PDF просто перестаёт производиться).
- Валидация конфига через отдельную схему (joi для конфига не вводим — `md-to-pdf`
  уходит, дом предупреждения — точечная ветка в оркестрации сборки).
- Автоправка/чистка `.c4builder` (только подсказка пользователю).

## Decisions

### Дом предупреждения — оркестрация сборки, а не отдельный валидатор
Предупреждение печатается в `build.js` на месте бывших вызовов
`generateCompletePDF`/`generatePDF` (сейчас `if (options.GENERATE_PDF)` /
`GENERATE_COMPLETE_PDF_FILE`). Это единственный choke point, срабатывающий один раз
за сборку и уже завязанный на нужные флаги.
*Альтернатива* — валидатор конфига в `cli.js`/joi: отвергнута, лишний слой ради
одного deprecated-случая; отдельной joi-схемы для конфига в проекте нет.

### Триггер — только truthy, список — только присутствующие truthy
Условие предупреждения — `GENERATE_PDF || GENERATE_COMPLETE_PDF_FILE` (truthy).
Критично: у большинства прошедших wizard конфигов ключи явно `false` (включая
fixture) — на них печатать нельзя, иначе шумит у всех и краснит golden. В сообщение
попадают только те ключи, что реально truthy (собираем список фильтром по значению),
как решено с пользователем.
*Альтернатива* — всегда печатать фиксированную тройку ключей: отвергнута (пугает
ключами, которых в конфиге нет).

### Конфиг не мутируется
На легаси-ключах не вызываем `conf.delete()` — только печать + подсказка. Причина:
ранее checksums намеренно вынесли из `.c4builder`, чтобы он не менялся при сборке;
побочная правка чужого файла из-за deprecated-флага противоречит этому.
*Альтернатива* — авто-удаление ключей: отвергнута (мутация без запроса, git-шум).

### gate'ы правим точечно
В `build.js` (создание dist-папок ~строка 102, копирование прочих файлов ~строка 145)
`GENERATE_PDF` слит через `||` с `GENERATE_MD`/`GENERATE_WEBSITE`. Убираем **только**
дизъюнкт `|| options.GENERATE_PDF`, блок остаётся живым для md/website.

### Wizard: убрать PDF из чекбокса И из undefined-гейта
Помимо PDF-пунктов чекбокса и блока `pdfCss`, убираем PDF-ключи из условия
`... === undefined` (`cli.collect.js`), которое решает, показывать ли вопрос формата.
Иначе конфиг без PDF-ключей будет вечно считаться «неполным» и ре-триггерить промпт.

### Опции конфига убираем, старые ключи в файле игнорируются
Из `getOptions` (`cli.js`) уходят `GENERATE_PDF`, `GENERATE_COMPLETE_PDF_FILE`,
`PDF_CSS`. Оставшиеся в чужих `.c4builder` ключи просто не читаются (configstore
хранит их без вреда) — кроме труthy-случая, который ловит предупреждение.

## Risks / Trade-offs

- **Молчаливое исчезновение PDF у активного пользователя PDF** → предупреждение
  явно называет удалённые ключи и что делать; выход не рушится.
- **Golden-тест краснеет из-за нового stdout/поведения** → fixture с PDF=false,
  предупреждение не срабатывает, дерево выходных файлов не меняется; эталон трогать
  не нужно. Проверяется прогоном golden после правок.
- **Забытая ветка кода с `GENERATE_PDF`** → пройтись `grep -rniE "pdf|md-to-pdf|
  puppeteer"` по коду после правок; в tasks есть верификационный шаг.
- **`description`/`keywords` в package.json остаются с «PDF»** (косметика) →
  включено в объём, чистится вместе с зависимостью.

## tasks

[Обзор](#C4-Builder)

# Tasks: remove-pdf

## 1. Рендер в build.js

- [x] 1.1 Удалить `require('md-to-pdf')` (строка 9)
- [x] 1.2 Удалить функцию `generateCompletePDF()` целиком
- [x] 1.3 Удалить функцию `generatePDF()` целиком
- [x] 1.4 В оркестрации заменить `if (options.GENERATE_PDF)` / `if (options.GENERATE_COMPLETE_PDF_FILE)`
      единой веткой-предупреждением (см. задачу 4)
- [x] 1.5 В gate создания dist-папок убрать дизъюнкт `|| options.GENERATE_PDF` (оставить MD/WEBSITE)
- [x] 1.6 В gate копирования прочих файлов убрать `|| options.GENERATE_PDF`; проверить, что
      `GENERATE_COMPLETE_PDF_FILE`-ветка копирования в корень уходит вместе с complete-PDF

## 2. Конфиг и опции (cli.js)

- [x] 2.1 Убрать из `getOptions` ключи `GENERATE_PDF`, `GENERATE_COMPLETE_PDF_FILE`, `PDF_CSS`
- [x] 2.2 Убрать упоминание PDF из предупреждения watch-режима (строки 147-148)

## 3. Мастер настройки (cli.collect.js)

- [x] 3.1 Убрать оба PDF-пункта (`generatePDF`, `generateCompletePDF`) из чекбокса форматов
      и соответствующие `conf.set(...)`
- [x] 3.2 Убрать PDF-ключи из `undefined`-гейта, решающего, показывать ли вопрос формата,
      и из массива `defaults`
- [x] 3.3 Удалить блок вопроса про `pdfCss` и его `conf.set('pdfCss', ...)`

## 4. Предупреждение для легаси-конфига

- [x] 4.1 В точке 1.4 собрать список truthy PDF-ключей из конфига
      (`generatePDF`, `generateCompletePDF`) — только реально присутствующие/истинные
- [x] 4.2 Если список непуст — напечатать предупреждение: PDF-вывод удалён, перечислить
      эти ключи, подсказать удалить их из `.c4builder` вручную; сборку не прерывать (exit 0)
- [x] 4.3 Убедиться, что конфиг НЕ мутируется (никаких `conf.delete`/`conf.set`)
- [x] 4.4 На `false`/отсутствующих ключах предупреждение не печатается

## 5. Docs и list

- [x] 5.1 `cli.help.js`: удалить блоки про «Generate multiple pdf files»,
      «Generate a single complete pdf file», «Custom PDF CSS»
- [x] 5.2 `cli.list.js`: удалить строки вывода `GENERATE_PDF`, `GENERATE_COMPLETE_PDF_FILE`,
      `PDF_CSS`

## 6. Зависимости и ассеты

- [x] 6.1 Удалить `md-to-pdf` из `dependencies` в `package.json`; `npm install` для обновления lock
- [x] 6.2 Убрать «PDF» из `description` и `keywords` в `package.json`
- [x] 6.3 Удалить файл `pdf.css`

## 7. Верификация

- [x] 7.1 `grep -rniE "pdf|md-to-pdf|puppeteer"` по `*.js`/`package.json` — не осталось
      живого PDF-кода (кроме осознанного текста предупреждения)
- [x] 7.2 Прогнать golden-тест: дерево выходов и эталон не изменились, тест зелёный
- [x] 7.3 Ручная проверка: конфиг с `generatePDF: true` → печатается предупреждение,
      md/website собираются, exit 0, `.c4builder` не изменён; конфиг с `false` → тишина
- [x] 7.4 `openspec validate remove-pdf --strict` проходит

## specs

[Обзор](#C4-Builder)

- [output-formats](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-remove-pdf/specs/output-formats/output-formats)

## output-formats

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Поддерживаемые типы вывода
Сборка SHALL поддерживать три типа вывода: множественные markdown-файлы
(`generateMD`), единый complete-markdown (`generateCompleteMD`) и website
(`generateWEB`). PDF-вывод (множественные PDF-файлы и единый complete-PDF)
MUST NOT поддерживаться, а зависимость `md-to-pdf` и связанный headless-браузер
MUST отсутствовать в зависимостях пакета.

#### Scenario: Сборка доступных выходов
- **WHEN** в `.c4builder` включены `generateMD`, `generateCompleteMD` и/или `generateWEB`
- **THEN** сборка формирует соответствующие выходы и не порождает PDF-файлов

#### Scenario: PDF-зависимость отсутствует
- **WHEN** просматриваются зависимости пакета
- **THEN** `md-to-pdf` (и транзитивный headless-браузер) в них отсутствует, файла `pdf.css` в пакете нет

### Requirement: Мастер настройки не предлагает PDF
Интерактивный мастер настройки (`c4builder config`) MUST NOT предлагать PDF-форматы
в выборе типов вывода и MUST NOT спрашивать про пользовательский PDF-CSS. Наличие
или отсутствие PDF-ключей в конфиге MUST NOT влиять на то, показывается ли вопрос
о выборе форматов.

#### Scenario: Выбор форматов в мастере
- **WHEN** пользователь запускает мастер настройки
- **THEN** в списке форматов присутствуют только markdown, complete-markdown и website, а вопрос про PDF-CSS не задаётся

#### Scenario: Конфиг без PDF-ключей не ре-триггерит вопрос
- **WHEN** запускается сборка с конфигом, где выбраны форматы, но PDF-ключи отсутствуют
- **THEN** мастер выбора форматов не показывается повторно из-за отсутствия PDF-ключей

### Requirement: Легаси-конфиг с PDF не ломает сборку
Сборка SHALL продолжаться и завершаться успешно (код возврата 0), собрав все прочие
включённые выходы, при наличии в существующем `.c4builder` истинного (truthy)
значения `generatePDF` и/или `generateCompletePDF`. Сборка MUST напечатать
предупреждение, что PDF-вывод удалён, перечислив в нём **только реально
присутствующие truthy PDF-ключи**, и подсказать удалить их из `.c4builder` вручную.
Сборка MUST NOT изменять файл конфигурации.

#### Scenario: Truthy PDF-ключ в конфиге
- **WHEN** в `.c4builder` `generatePDF: true` и включены другие выходы
- **THEN** печатается предупреждение с ключом `generatePDF` и подсказкой удалить его, markdown/website собираются, процесс завершается с кодом 0, а `.c4builder` остаётся без изменений

#### Scenario: В предупреждении только присутствующие ключи
- **WHEN** truthy только `generateCompletePDF`, а `generatePDF` равен `false` или отсутствует
- **THEN** предупреждение перечисляет `generateCompletePDF` и не упоминает `generatePDF`

#### Scenario: PDF выключен или не задан
- **WHEN** `generatePDF` и `generateCompletePDF` равны `false` или отсутствуют в конфиге
- **THEN** предупреждение о PDF не печатается

## 2026-07-05-new-noninteractive

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="17" max="17"></progress> 17/17 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-new-noninteractive/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-new-noninteractive/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-new-noninteractive/specs/specs)

# Неинтерактивный `c4builder --new`

> **Зависит от:** `remove-pdf` (полный конфиг без PDF-ключей), `remove-plantuml-version`
> (в `new` уже нет выбора версии → без флага `--plantuml-version`).
> **Порядок:** последний в cleanup-ветке.

## Why

`c4builder --new` сейчас чисто интерактивный: три `inquirer`-промпта (имя проекта,
версия PlantUML, VSCode-сниппеты), все переданные флаги игнорируются. Это блокирует
скриптовое/CI-создание проектов и сценарии с AI-агентами — им нужен предсказуемый
запуск без диалога. Плюс даже после `--new` первая сборка всё равно открывает wizard
форматов (`cmdCollect`), так что «headless scaffold» сегодня невозможен в принципе.

## What Changes

- **`--new` принимает флаги**: `--name <name>`, `--vscode` / `--no-vscode` (дефолт
  `true`). Переданные значения подставляются вместо соответствующих промптов.
  (Выбор версии PlantUML к этому моменту уже удалён change'ем `remove-plantuml-version`,
  поэтому флага версии нет.)
- **Явный неинтерактивный режим `-y` / `--yes`** (npm-стиль): без него — промпт
  только для того, что не задано флагом (флаги = пре-филл). С `--yes` — **ни одного
  промпта**: `--name` обязателен, для остального берутся дефолты, а невалидное
  имя/версия дают **понятную ошибку и ненулевой код возврата**, а не ре-промпт.
- **В режиме `--yes` `new` пишет полный `.c4builder`** (форматы + под-опции), чтобы
  последующий `c4builder` не открывал wizard. Дефолты выходов: website + множественные
  markdown, `diagramFormat=svg`, локальный рендер, `UTF-8`.
- **Единый источник дефолтов.** Значения по умолчанию выносятся в общий
  `defaultConfig`, который пишет `new --yes` и из которого wizard берёт свои дефолты —
  чтобы «полный конфиг» и wizard не разъезжались.
- Убирается отладочный `console.log(isVSCode)` (`cli.new.js`).

## Capabilities

### New Capabilities
- `project-scaffold`: как `c4builder --new` создаёт проект — интерактивно и
  неинтерактивно (флаги + `--yes`), валидация в неинтерактиве как ошибки, запись
  полного `.c4builder` для headless-сборки.

## Impact

- `cli.js`: новые опции `--name`, `--vscode/--no-vscode`, `-y/--yes`; проброс `opts`
  в `cmdNewProject(opts)`.
- `cli.new.js`: промпты становятся условными (пропуск при заданном флаге; при `--yes`
  — без промптов, дефолты, жёсткая валидация); запись полного `.c4builder` в `--yes`;
  удаление debug-лога.
- Новый общий `defaultConfig` (значения по умолчанию), используемый `cli.new.js` и
  `cli.collect.js`.
- **Порядок в цепочке — после `remove-pdf` и `remove-plantuml-version`**: тогда
  «полный конфиг» не содержит PDF-ключей (не решаем про `generatePDF`), а команда `new`
  уже без выбора версии (флаг `--plantuml-version` не вводится).
- **Вне объёма**: флаги выбора форматов (`--md/--website/...`) — тонкая настройка
  через правку `.c4builder`; неинтерактивность самого wizard'а сборки для проектов,
  созданных не через `--new` (здесь закрывается только `new`-путь).
- **Не затрагивается** содержимое шаблона (`project-template`), golden/CI.

## design

[Обзор](#C4-Builder)

## Context

`c4builder --new` (`--new`-флаг, не подкоманда) вызывает `cmdNewProject()`, который
игнорирует `opts` и всегда задаёт `inquirer`-вопросы: `projectName` (с валидацией на
слэши и непустую папку) и `isVSCode`. Затем копирует шаблон, пишет `.c4builder`
(`projectName` [+ рендер-настройки]), README и опц. `.vscode`-сниппеты.

Предусловие: этот change идёт после `remove-plantuml-version`, поэтому вопрос/флаг
версии PlantUML здесь уже не существует (был `plantumlVersion`-промпт — удалён там).

Отдельно `cmdCollect` (wizard сборки) пишет полный набор ключей (`generateMD`,
`generateWEB`, `includeNavigation`, `diagramFormat`, `charset`, …). Поэтому даже после
`--new` первая сборка открывает wizard — headless-поток сегодня невозможен.

## Goals / Non-Goals

**Goals:**
- Флаги для вопросов `--new` (имя, VSCode) + явный `--yes` (ноль промптов).
- В `--yes` валидация как ошибки+exit≠0 (CI-безопасно), а не ре-промпт.
- В `--yes` — полный `.c4builder`, чтобы последующая сборка не спрашивала.
- Единый `defaultConfig` для `new --yes` и wizard'а (дефолты не разъезжаются).

**Non-Goals:**
- Флаги выбора форматов (`--md/--website/...`) — тонкая настройка правкой `.c4builder`.
- Неинтерактивность wizard'а сборки для «чужих» проектов (не через `--new`).
- Менять содержимое шаблона (`project-template`) или golden/CI.

## Decisions

### `--yes` npm-стиль, а не «магия по наличию --name»
Явный `-y/--yes` разделяет намерения: без него промпт только для незаданного (пре-филл
флагами, удобно людям); с ним — гарантированный no-prompt (CI/агенты). Наличие `--name`
как неявный триггер отвергнуто: неочевидно и не даёт «задать имя, но спросить версию».

### Полный конфиг в `--yes` через общий `defaultConfig`
`new --yes` пишет тот же набор ключей, что и wizard, значениями из `defaultConfig`.
Дефолты выходов: website + множественные markdown, `diagramFormat=svg`, локальный
рендер, `UTF-8` (форма — как у эталонного `.c4builder` fixture, но без PDF).
*Альтернатива* — хардкодить полный конфиг прямо в `cli.new.js`: отвергнута, разъедется
с дефолтами wizard'а. Поэтому дефолты выносятся в один модуль, из которого их читает и
wizard (как `default` в inquirer-промптах).

### Валидация — общая функция, два поведения
Проверки имени (слэши, непустая папка) и версии уже есть в `cli.new.js`/`cli.collect`.
Выносим в переиспользуемую проверку: в интерактиве — как сейчас (ре-промпт), в `--yes`
— бросаем ошибку с понятным текстом и ненулевым exit.

### Проброс opts
`cli.js` парсит новые опции и передаёт `cmdNewProject(opts)`. Внутри каждый промпт
условен: если значение пришло флагом — берём его; иначе при `--yes` — дефолт, при
интерактиве — спрашиваем.

## Risks / Trade-offs

- **Дрейф «полного конфига» от реального набора ключей wizard'а** → единый
  `defaultConfig` + (желательно) тест: `new --yes` → `c4builder` собирает без промптов.
- **Дефолт рендера для headless**: `generateLocalImages` должен быть согласован
  (локальный рендер) прямо в `defaultConfig`, чтобы headless-сборка не зависела от
  внешних условий.
- **Зависимости**: делать после `remove-pdf` (иначе «полный конфиг» решает про
  `generatePDF`) и после `remove-plantuml-version` (иначе пришлось бы вводить флаг
  `--plantuml-version`, который тот change убирает).

## Open Questions

- Точный дефолтный набор выходов: website + md — достаточно, или добавить
  complete-md? Стартовое предложение — website + md; уточнить при реализации.
- Нужен ли `--force` для перезаписи непустой папки в `--yes`, или всегда ошибка?
  Склоняюсь к ошибке (безопаснее); `--force` — при явном запросе.

## tasks

[Обзор](#C4-Builder)

# Tasks: new-noninteractive

> Зависимости: делать после `remove-pdf` (полный конфиг без PDF-ключей) и после
> `remove-plantuml-version` (в `new` уже нет выбора версии — флаг `--plantuml-version` не вводим).

## 1. Общий defaultConfig

- [x] 1.1 Вынести значения по умолчанию проекта в единый модуль/объект `defaultConfig`
      (выходы: website + md, `diagramFormat=svg`, локальный рендер, `UTF-8`, под-опции)
- [x] 1.2 Переключить дефолты wizard'а (`cli.collect.js`) на `defaultConfig`
      (значения `default` промптов берутся оттуда) — без изменения интерактивного поведения

## 2. Флаги CLI (cli.js)

- [x] 2.1 Добавить опции `--name <name>`, `--vscode` / `--no-vscode`, `-y, --yes`
- [x] 2.2 Пробросить `opts` в `cmdNewProject(opts)`

## 3. Условные промпты и валидация (cli.new.js)

- [x] 3.1 Сделать промпты (имя, VSCode) условными: значение из флага → без вопроса
- [x] 3.2 Вынести валидацию имени (слэши, непустая папка) и версии в переиспользуемую
      функцию: интерактив — ре-промпт (как сейчас), `--yes` — ошибка + exit≠0
- [x] 3.3 В `--yes` при отсутствии `--name` — понятная ошибка + exit≠0, без промптов
- [x] 3.4 Удалить debug `console.log(isVSCode)` (строка 161)

## 4. Запись полного конфига в --yes

- [x] 4.1 В `--yes` записывать полный `.c4builder` из `defaultConfig` + значений флагов
      (projectName, plantumlVersion), достаточный для сборки без wizard'а
- [x] 4.2 Интерактивный путь оставить как есть (пишет только projectName+plantumlVersion)
- [x] 4.3 Согласовать `generateLocalImages`/рендер в `defaultConfig` (не зависеть от
      ветки «только пинованная версия»)

## 5. Верификация

- [x] 5.1 `c4builder --new --yes --name demo` в пустой папке → без промптов, exit 0
- [x] 5.2 Далее `c4builder` в созданном проекте → сборка без интерактивных вопросов
- [x] 5.3 `--new --yes` без `--name` и с занятой папкой → понятная ошибка, exit≠0, без промптов
- [x] 5.4 Частичный пре-филл без `--yes` (`--name demo`) → спрашивает только версию/VSCode
- [x] 5.5 Дефолты `new --yes` совпадают с дефолтами wizard'а (единый источник)
- [x] 5.6 `openspec validate new-noninteractive --strict` проходит

## specs

[Обзор](#C4-Builder)

- [project-scaffold](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-new-noninteractive/specs/project-scaffold/project-scaffold)

## project-scaffold

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Флаги команды создания проекта
Команда `c4builder --new` SHALL принимать значения через флаги: `--name <name>`
(имя проекта), `--vscode` / `--no-vscode` (включение VSCode-сниппетов, дефолт включено).
Переданное флагом значение MUST подставляться вместо соответствующего интерактивного вопроса.

#### Scenario: Флаг заменяет промпт
- **WHEN** `c4builder --new --name demo --no-vscode` без `--yes`
- **THEN** вопросы про имя и VSCode-сниппеты не задаются, а недостающие (если
  бы были) — спрашиваются интерактивно

### Requirement: Явный неинтерактивный режим
С флагом `-y` / `--yes` создание проекта SHALL проходить без единого интерактивного
вопроса. В этом режиме `--name` MUST быть задан; отсутствие `--name` или невалидное
значение (имя со слэшем, непустая целевая папка) MUST приводить к
понятной ошибке и ненулевому коду возврата, а НЕ к повторному запросу. Неуказанные
флагами значения MUST браться из дефолтов.

#### Scenario: Полностью неинтерактивное создание
- **WHEN** `c4builder --new --yes --name demo` в пустой директории
- **THEN** проект создаётся без промптов, процесс завершается с кодом 0

#### Scenario: --yes без имени
- **WHEN** `c4builder --new --yes` без `--name`
- **THEN** создание завершается понятной ошибкой и ненулевым кодом возврата, без промптов

#### Scenario: --yes с занятой папкой
- **WHEN** `c4builder --new --yes --name demo`, а папка `demo` существует и не пуста
- **THEN** создание завершается понятной ошибкой и ненулевым кодом возврата, без промптов

### Requirement: Полный конфиг для headless-сборки
В режиме `--yes` создание проекта SHALL записывать в `.c4builder` полный набор
настроек (типы выходов и их под-опции, формат диаграмм, кодировку, локальный рендер),
достаточный, чтобы последующий запуск `c4builder` собрал проект без интерактивного
wizard'а. Значения по умолчанию для выходов MUST включать website и множественные
markdown, `diagramFormat=svg`, локальный рендер диаграмм и `UTF-8`.

#### Scenario: Сборка после --yes не спрашивает
- **WHEN** проект создан через `c4builder --new --yes --name demo`, затем в нём
  запущен `c4builder`
- **THEN** сборка проходит без интерактивных вопросов и формирует выходы по
  записанным дефолтам

#### Scenario: Интерактивное создание не пишет полный конфиг
- **WHEN** проект создан интерактивно (без `--yes`)
- **THEN** поведение записи `.c4builder` остаётся прежним, а первая сборка ведёт
  пользователя через wizard как раньше

### Requirement: Единый источник значений по умолчанию
Значения по умолчанию для настроек проекта SHALL задаваться в едином месте
(`defaultConfig`), которое используется и при записи полного конфига в режиме `--yes`,
и как источник дефолтов интерактивного wizard'а. Дефолты в неинтерактивном создании и
в wizard'е MUST совпадать.

#### Scenario: Совпадение дефолтов
- **WHEN** сравниваются значения по умолчанию, предлагаемые wizard'ом, и значения,
  записанные `new --yes` без явных флагов
- **THEN** они совпадают (единый источник, без дублирования)

## 2026-07-05-jre-resolver

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="20" max="20"></progress> 20/20 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/specs/specs)

# JRE-резолвер: системная java → кеш → публичный Adoptium

## Why

После `plantuml-java-direct` рендер зовёт `spawn('java', …)` — голую `java` из PATH
(`build.js`). Нет проверки версии, нет запасного источника: если java не на PATH,
рендер падает событием `error` с «java не найдена». На корп-машине или в чистом
контейнере без установленной Java c4builder не работает из коробки, а сообщение об
ошибке невнятное.

Типовое решение `njre` не подходит: оно хардкодит github-releases Adoptium (зеркала
не подставить), тянет полный JDK, давно не развивается и не даёт контроля версии/кеша.
Нужен свой минимальный резолвер: найти годную системную java, иначе — переиспользовать
ранее скачанный JRE, иначе — скачать Temurin 21 с публичного Adoptium.

**Решение по источнику (осознанно):** корпоративное Artifactory-зеркало Temurin **не
вводится**. C4-Builder живёт в публичной группе `ai-sandbox` — корп-URL там неуместен
(внутренняя деталь). Единственный сетевой источник — публичный `api.adoptium.net`.
**Допущение:** он доступен в целевой среде (принято при проектировании).

## What Changes

- **`resolveJava()` — приоритетная цепочка** (один раз за сборку): системная
  (`JAVA_HOME` → `PATH`, мажор **≥ 17**) → локальный кеш → автоскачивание **Temurin 21
  JRE** с публичного Adoptium. Первый подошедший источник используется.
- **java-бинарь передаётся в рендер.** `renderDiagram` вызывает `spawn(javaBin, …)`
  вместо `spawn('java', …)`; путь резолвится один раз в `generateImages`.
- **Резолв ленивый.** JRE резолвится, только если в дереве есть хотя бы одна PlantUML
  (`.puml`) диаграмма; проект целиком на D2 java не трогает.
- **Команда прогрева `c4builder jre install`** — резолвит/скачивает JRE заранее для
  CI/офлайн, без запуска полной сборки.
- **Целостность.** Ссылка и `sha256` берутся из Adoptium assets API; скачанный архив
  проверяется по контрольной сумме перед распаковкой.
- **Кросс-платформенная распаковка** архива (`tar.gz` для linux/mac, `zip` для windows)
  через `tar` + `yauzl`.
- **Внятная ошибка** при полном провале цепочки: подсказать «поставить JRE 17+ или
  запустить `c4builder jre install`».

## Capabilities

### Added Capabilities
- `jre-resolution`: определение исполняемого файла Java по приоритетной цепочке
  (система → кеш → публичный Adoptium), годность системной java по мажорной версии,
  автоскачивание Temurin 21 JRE с проверкой sha256, кеширование и переиспользование,
  ленивый резолв + команда прогрева, понятная ошибка при провале.

### Modified Capabilities
- `diagram-rendering`: требование «Рендер вызывает java напрямую» уточняется —
  исполняемый файл Java определяется резолвером (см. `jre-resolution`), а не берётся
  безусловно как голая `java` из PATH. Прочие аспекты (pipe-режим, имя выходного файла)
  без изменений.

## Impact

- `build.js`: в `generateImages` — один резолв `const javaBin = await resolveJava()`
  перед циклом, только при наличии PlantUML-диаграмм; `renderDiagram` принимает
  `javaBin` и спавнит его вместо строкового `'java'`.
- Новый модуль `jre.js`: детект системной java, кеш-каталог, загрузчик Adoptium
  (assets API → sha256 → распаковка), маппинг `process.platform`/`arch`.
- CLI: подкоманда `jre install` (прогрев кеша); опционально `jre status`.
- `package.json`: `tar`, `yauzl` в `dependencies` (распаковка tar.gz/zip).
- **Порядок в цепочке:** после `plantuml-java-direct` (там появилась точка вызова
  java). Независимо от `d2-backend`, `resvg-png`, `remove-pdf`.
- **Не затрагивается:** golden-fixture и CI — там java 21 ставится через `setup-java`,
  то есть срабатывает ветка «системная годная», скачивание не триггерится, layout не
  меняется. Спеки `regression-testing`/`ci-validation` не трогаем.

## design

[Обзор](#C4-Builder)

## Context

`plantuml-java-direct` заменил `node-plantuml` прямым `spawn('java', argv)` в
`renderDiagram` (`build.js`). `java` берётся голой из PATH: нет проверки версии, нет
запасного пути. Нет java на PATH → `child.on('error')` → «java не найдена». Это change
о том, **как находится сам бинарь java**, а не как строится команда PlantUML.

Идёт **строго после** `plantuml-java-direct` (там появилась точка вызова java).
С `d2-backend`, `resvg-png`, `remove-pdf` не пересекается.

## Goals / Non-Goals

**Goals:**
- Работать из коробки на машине без Java: скачать JRE самостоятельно.
- Переиспользовать системную java, когда она годна (не качать зря).
- Детерминизм CI не ломать: где стоит Temurin 21 (setup-java) — берём системную.
- Ленивость: проект без PlantUML java не резолвит; отдельный прогрев для CI/офлайн.

**Non-Goals:**
- Корпоративное/приватное зеркало Adoptium (публичный репо — не вводим; при спросе —
  отдельная надстройка `C4BUILDER_JRE_MIRROR` без корп-дефолта).
- Управление несколькими версиями/вендорами JRE (тянем ровно Temurin 21 JRE).
- Оффлайн-скачивание без сети (прогрев `jre install` требует сети один раз).
- Экспериментальный TeaVM-движок (PlantUML без Java) — отдельная ветка, вне объёма;
  но резолвер должен быть обходим (вызывается только для PlantUML-пути).

## Decisions

### Приоритетная цепочка: система → кеш → скачивание
Первый годный источник выигрывает. Системная первой — уважает уже поставленную java
(и детерминизм CI). Кеш вторым — раз скачав, не качаем повторно. Скачивание последним.
*Альтернатива* — всегда качать свой JRE (детерминизм у всех одинаковый): отвергнута —
навязчиво, лишний трафик, игнорирует рабочую java.

### Годность системной java — мажор ≥ 17
`java -version` → парс мажорной версии; ≥ 17 принимаем. PlantUML жив и на java 8, но
17 — разумный современный минимум и совпадает с заявленным в `cli.new`.
*Trade-off:* layout текста версионно-зависим (AWT font metrics), поэтому картинки на
java 17 и 21 могут чуть отличаться. Приемлемо: golden — внутренний тест (CI на 21),
для пользователя мелкие вариации layout некритичны.

### Источник — только публичный Adoptium, без зеркала
Единственный сетевой источник — `api.adoptium.net`. Корп-Artifactory-зеркало
сознательно не вводим: C4-Builder публичный (`ai-sandbox`), корп-URL там неуместен.
**Допущение:** Adoptium доступен в целевой среде (принято явно).
*Почему не njre:* хардкодит github-releases, зеркала не подставить, тянет JDK, не
развивается — свой резолвер меньше и под контролем.

### Целостность через Adoptium assets API
Запрос `GET /v3/assets/latest/21/hotspot?os=..&architecture=..&image_type=jre&vendor=eclipse`
отдаёт JSON с `binary.package.link` и `binary.package.checksum` (sha256) сразу. Качаем
по `link`, сверяем sha256 до распаковки; несовпадение → ошибка, кеш не заполняется.
`binary`-эндпоинт даёт 307-редирект на github — тоже рабочий вариант, но assets отдаёт
и ссылку, и контрольную сумму одним запросом.

### Хранилище — пользовательский кеш (XDG)
`~/.cache/c4builder/jre/temurin-21-<os>-<arch>/` (Windows — `%LOCALAPPDATA%`). Ключ =
версия+ОС+архитектура. Не в `node_modules` — переживает переустановку пакета и общий
для проектов. Валидность = наличие `bin/java`(`.exe`); битую установку перекачиваем.

### Платформы автоматически из process.*
`process.platform` → `linux|mac|windows`, `process.arch` → `x64|aarch64` маппятся в
параметры Adoptium. Код один на все пары; различается лишь формат архива и путь к
бинарю (`bin/java` vs `bin\java.exe`).

### Распаковка — tar + yauzl
В Node нет встроенной распаковки. `tar.gz` (linux/mac) → пакет `tar`; `zip` (windows)
→ `yauzl`. Чистый Node, не зависит от системных утилит (в отличие от спавна `tar`).
*Альтернатива* — спавнить системный `tar`/bsdtar: отвергнута, хрупко на старых Windows.

### Ленивый резолв + команда прогрева
Резолв только при наличии `.puml` в дереве (проект на D2 java не трогает). Дополнительно
`c4builder jre install` — прогрев кеша заранее (CI/офлайн), без полной сборки.

### Точка вклинивания
`generateImages` (`build.js`): один `const javaBin = await resolveJava()` перед циклом,
если среди диаграмм есть `engine === 'plantuml'`. `renderDiagram` принимает `javaBin` в
опциях и спавнит его вместо строки `'java'`. Больше ничего в рендере не меняется.

## Risks / Trade-offs

- **Adoptium недоступен, java нет, кеш пуст** → сборка не может рендерить PlantUML.
  Митигация: понятная ошибка с двумя действиями (поставить JRE / `jre install`); D2 при
  этом работает. Допущение о доступности Adoptium принято осознанно.
- **Первое скачивание ~40–50 МБ** тормозит первую сборку. Митигация: `jre install` для
  прогрева; кеш переиспользуется.
- **Layout между версиями java** (17 vs 21) может дрогнуть. Приемлемо (см. Decisions);
  для строгой воспроизводимости можно позже добавить «forced managed JRE».
- **Native/платформенный архив не для той arch** (musl vs glibc на alpine) → Adoptium
  различает; при неизвестной паре — понятная ошибка, не молчаливый провал.

## Open Questions

- `jre install` при годной системной java — ставить всё равно (форс-скачивание) или
  сообщать «системная годна, скачивание не требуется»? Предлагаю по умолчанию второе,
  с флагом `--force` для форса. Решить при реализации CLI.
- Нужен ли `jre status` (показать, откуда резолвится java) — необязателен, добавить при
  спросе.
- Пин конкретной сборки Temurin 21 (для 100% воспроизводимости) против «latest 21 ga».
  Стартуем с latest ga; пин — если понадобится строгий детерминизм.

## tasks

[Обзор](#C4-Builder)

# Tasks: jre-resolver

> Предусловие: выполняется ТОЛЬКО после `plantuml-java-direct` (там появилась точка
> вызова java). Независимо от `d2-backend`/`resvg-png`/`remove-pdf`.

## 1. Зависимости

- [x] 1.1 Добавить `tar` и `yauzl` в `dependencies`; зафиксировать (пин) версии

## 2. Модуль резолвера (`jre.js`)

- [x] 2.1 `resolveJava()` — приоритетная цепочка: системная → кеш → скачивание;
      возвращает абсолютный путь к бинарю `java`; первый годный источник выигрывает
- [x] 2.2 Детект системной: `JAVA_HOME/bin/java`, затем `PATH`; `java -version` → парс
      мажорной версии; годна при мажоре ≥ 17; отсутствие/ошибка запуска — переход к
      следующему источнику (не падение)
- [x] 2.3 Кеш: путь `~/.cache/c4builder/jre/temurin-21-<os>-<arch>/` (Windows —
      `%LOCALAPPDATA%`); валидность = наличие `bin/java`(`.exe`); битую установку
      перекачивать
- [x] 2.4 Загрузчик Adoptium: assets API (`/v3/assets/latest/21/hotspot?...image_type=jre&vendor=eclipse`)
      → `{ link, sha256 }`; скачать по link; сверить sha256 ДО распаковки; несовпадение
      → ошибка, кеш не заполнять
- [x] 2.5 Маппинг `process.platform`/`process.arch` → `os`/`arch` Adoptium; выбор
      формата архива (`tar.gz` linux/mac → `tar`, `zip` windows → `yauzl`); распаковка
      в кеш
- [x] 2.6 Понятная ошибка при полном провале цепочки (поставить JRE 17+ либо
      `c4builder jre install`), без сырого стектрейса spawn

## 3. Встраивание в `build.js`

- [x] 3.1 В `generateImages` резолвить `javaBin` один раз ПЕРЕД циклом, только если в
      дереве есть хотя бы одна `engine === 'plantuml'` диаграмма
- [x] 3.2 `renderDiagram` принимает `javaBin` в опциях; `spawn(javaBin, argv)` вместо
      `spawn('java', argv)`
- [x] 3.3 Проект без `.puml` (только `.d2`) → `resolveJava` не вызывается, скачивание
      не инициируется

## 4. CLI — прогрев

- [x] 4.1 Подкоманда `c4builder jre install`: резолвит/скачивает JRE в кеш заранее, без
      полной сборки; печатает путь и версию
- [x] 4.2 (open) Поведение при годной системной java: сообщать «скачивание не требуется»
      против флага `--force` (см. design Open Questions) — решено: дефолт сообщает,
      `--force` форсирует загрузку

## 5. Верификация

- [x] 5.1 Системная java 17+ есть → используется, скачивание не выполняется, сеть не
      задействуется
- [x] 5.2 Системной java нет → скачивается Temurin 21 JRE под текущую платформу, sha256
      совпадает, PlantUML-диаграммы рендерятся
- [x] 5.3 Второй прогон → java берётся из кеша, без сети
- [x] 5.4 Проект только из `.d2` → java не резолвится, скачивания нет
- [x] 5.5 Офлайн, нет системной java и пустой кеш → понятная ошибка с двумя действиями,
      D2-рендер (если есть) при этом работает
- [x] 5.6 `c4builder jre install` → JRE в кеше, последующая сборка не качает
- [x] 5.7 Golden CI (Temurin 21 через `setup-java`) зелёный: срабатывает ветка
      «системная годная», layout не меняется (golden red только на `class.svg` —
      предсуществующий дрейф glyph-рендера, воспроизводится без этого change)
- [x] 5.8 `openspec validate jre-resolver --strict` проходит

## specs

[Обзор](#C4-Builder)

- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/specs/diagram-rendering/diagram-rendering)
- [jre-resolution](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-jre-resolver/specs/jre-resolution/jre-resolution)

## diagram-rendering

[Обзор](#C4-Builder)

## MODIFIED Requirements

### Requirement: Рендер вызывает java напрямую
Сборка SHALL запускать PlantUML прямым вызовом Java с вендорным JAR, без посреднической
библиотеки `node-plantuml`. Исполняемый файл Java MUST определяться резолвером JRE
(см. capability `jre-resolution`: системная → кеш → публичный Adoptium), а не браться
безусловно как голая `java` из `PATH`. Источником данных MUST быть stdin/stdout
(pipe-режим), чтобы имя выходного файла определялось c4builder по имени `.puml`-файла,
а не по имени диаграммы из директивы `@startuml`.

#### Scenario: Имя выходного файла независимо от @startuml
- **WHEN** рендерится диаграмма, у которой в `@startuml <name>` задано имя, отличное от имени файла
- **THEN** выходной файл именуется по имени `.puml`-файла (как прежде), а не по `<name>`

#### Scenario: Локальные и stdlib-инклюды резолвятся
- **WHEN** рендерится диаграмма с `!include <C4/...>` (stdlib) и `!include ../styles.iuml` (локальный файл)
- **THEN** оба вида инклюдов резолвятся, диаграмма собирается корректно

#### Scenario: Java берётся из резолвера, а не голой из PATH
- **WHEN** годной системной java на `PATH` нет, но JRE доступен через кеш или скачивание
- **THEN** рендер использует резолвнутый бинарь Java и успешно рендерит диаграммы, а не
  падает с «java не найдена»

## jre-resolution

[Обзор](#C4-Builder)

## ADDED Requirements

### Requirement: Исполняемый файл Java резолвится по приоритетной цепочке
Сборка SHALL определять исполняемый файл Java по приоритетной цепочке источников:
(1) системная java (`JAVA_HOME`, затем `PATH`); (2) ранее скачанный JRE в локальном
кеше; (3) автоскачивание с публичного Adoptium. Первый годный источник MUST
использоваться, а последующие MUST NOT проверяться. Резолв MUST выполняться один раз за
сборку, а не на каждую диаграмму.

#### Scenario: Годная системная java — сеть не задействуется
- **WHEN** в системе есть годная java, а в проекте есть PlantUML-диаграммы
- **THEN** используется системная java, кеш и сеть не задействуются

#### Scenario: Системной нет, но JRE в кеше
- **WHEN** годной системной java нет, но в кеше есть ранее скачанный JRE
- **THEN** используется JRE из кеша, скачивание не выполняется

#### Scenario: Нет ни системной, ни кеша
- **WHEN** нет годной системной java и кеш пуст
- **THEN** выполняется скачивание JRE с публичного Adoptium

### Requirement: Годность системной java определяется мажорной версией
Системная java SHALL приниматься, если её мажорная версия ≥ 17 (определяется через
`java -version`). При меньшей версии система MUST считаться негодной, а резолвер MUST
переходить к следующему источнику. Отсутствие java или ошибка её запуска MUST NOT
прерывать сборку, а MUST вести к переходу на следующий источник цепочки.

#### Scenario: java 17+ принимается
- **WHEN** системная `java -version` сообщает мажорную версию ≥ 17
- **THEN** эта java используется для рендера

#### Scenario: Слишком старая java отвергается
- **WHEN** системная java имеет мажорную версию меньше 17
- **THEN** она не используется, резолвер переходит к кешу/скачиванию

#### Scenario: java не найдена — не падаем
- **WHEN** `java` отсутствует на `PATH` и `JAVA_HOME` не задан
- **THEN** резолвер не прерывается ошибкой, а переходит к следующему источнику

### Requirement: Автоскачивание Temurin 21 JRE с проверкой целостности
При необходимости скачивания сборка SHALL получать JRE **Temurin 21** (`image_type=jre`,
`vendor=eclipse`, hotspot) с публичного Adoptium под текущие ОС и архитектуру
(из `process.platform`/`process.arch`). Ссылка на архив и его контрольная сумма MUST
браться из Adoptium assets API; скачанный архив MUST проверяться по `sha256` до
распаковки; несовпадение MUST прерывать установку с ошибкой и не заполнять кеш.
Корпоративные/приватные зеркала как источник MUST NOT вводиться.

#### Scenario: Скачивание под текущую платформу
- **WHEN** выполняется скачивание JRE
- **THEN** `process.platform`/`process.arch` отображаются в параметры Adoptium
  (`os`/`arch`), и запрашивается архив под эту платформу

#### Scenario: Контрольная сумма совпала
- **WHEN** архив скачан и его `sha256` совпадает с суммой из assets API
- **THEN** архив распаковывается в кеш и используется

#### Scenario: Контрольная сумма не совпала
- **WHEN** `sha256` скачанного архива не совпадает с ожидаемым
- **THEN** установка прерывается ошибкой, кеш не заполняется

### Requirement: Скачанный JRE кешируется и переиспользуется
Скачанный и распакованный JRE SHALL храниться в пользовательском кеше под ключом
«версия + ОС + архитектура» и переиспользоваться последующими сборками без повторного
скачивания. Установка MUST считаться валидной только при наличии исполняемого
`bin/java` (`bin\java.exe` на Windows); неполная/битая установка MUST перекачиваться.

#### Scenario: Повторный запуск берёт JRE из кеша
- **WHEN** JRE уже скачан в кеш, запускается новая сборка без годной системной java
- **THEN** используется JRE из кеша, повторного скачивания и обращения к сети нет

#### Scenario: Битая установка перекачивается
- **WHEN** каталог кеша есть, но исполняемого `bin/java` в нём нет
- **THEN** установка считается невалидной и JRE скачивается заново

### Requirement: Резолв JRE ленивый и доступен командой прогрева
Резолв JRE SHALL выполняться лениво — только если в дереве проекта есть хотя бы одна
PlantUML-диаграмма (`.puml`). Проект без PlantUML-диаграмм (например, целиком на D2)
MUST NOT инициировать резолв или скачивание JRE. Дополнительно CLI SHALL предоставлять
команду прогрева (`c4builder jre install`), которая резолвит/скачивает JRE заранее (для
CI/офлайн) без запуска полной сборки.

#### Scenario: Проект без PlantUML не трогает java
- **WHEN** в проекте нет ни одного `.puml`-файла (например, только `.d2`)
- **THEN** резолв java не выполняется и JRE не скачивается

#### Scenario: Прогрев кеша командой
- **WHEN** выполняется `c4builder jre install` на машине без годной системной java
- **THEN** JRE скачивается и оказывается в кеше готовым, полная сборка не запускается

### Requirement: Понятная ошибка при невозможности резолва
Сборка SHALL завершаться понятной ошибкой, если ни один источник цепочки не дал рабочей
java (нет годной системной, кеш пуст, скачивание не удалось). Сообщение об ошибке MUST
указывать на два действия: установить JRE 17+ или запустить `c4builder jre install`, и
MUST NOT быть невнятным стектрейсом от `spawn`.

#### Scenario: Офлайн без java и кеша
- **WHEN** нет годной системной java, кеш пуст, а скачивание недоступно (нет сети)
- **THEN** сборка завершается понятным сообщением с подсказкой поставить JRE 17+ или
  запустить `c4builder jre install`, а не сырой ошибкой запуска процесса

## 2026-07-05-golden-matrix

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="18" max="18"></progress> 18/18 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-golden-matrix/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-golden-matrix/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-golden-matrix/specs/specs)

# golden-matrix — матрица golden-конфигураций + пин JVM

## Why

Два триггера, оба блокируют предстоящий TS-порт с рефакторингом compose-слоя:

1. **Односторонняя сетка.** Golden-тест гоняет один fixture-конфиг (website + md +
   complete-md, svg, navigation/TOC/breadcrumbs). Ветки `embedDiagram`,
   `includeLinkToDiagram`, `diagramsOnTop`, `excludeOtherFiles` и png-растеризация
   (resvg) эталоном не зафиксированы. Рефакторинг `build.js` (три копии замыкания
   `getDiagram` — build.js:459/587/687) без покрытия этих веток — прыжок веры.
2. **Периодические расхождения локально/CI.** Требование «локальный прогон совпадает
   с CI» нарушается: одинакового мажора JDK недостаточно. Дистрибутивные сборки
   OpenJDK (напр. Arch линкует системный freetype) дают иные метрики шрифта, чем
   Temurin на CI, → другие `textLength`/координаты в SVG → ложные диффы эталона.

## What Changes

- Golden-тест параметризуется **матрицей fixture-конфигураций** поверх одних и тех же
  исходников `template/src`:
  - `default` — текущий конфиг (website + md + complete-md, svg, navigation/TOC/breadcrumbs);
  - `links-top` — `includeLinkToDiagram` + `diagramsOnTop` + `excludeOtherFiles`,
    без navigation/TOC/breadcrumbs (противоположные значения переключателей default);
  - `embed-png` — `embedDiagram` + `diagramFormat=png` (растеризация SVG→PNG через
    resvg, нативный ditaa-PNG, base64-встраивание в md).
- Эталон реорганизуется: `test/golden/<variant>/` (manifest.json + tree/) вместо
  единого `test/golden/`. `UPDATE_GOLDEN=1` регенерирует все варианты разом.
- **Golden-сборки идут на пиновом managed JRE**: тест-хелпер прогревает кеш
  jre-резолвера (Temurin 21) и подставляет `JAVA_HOME` на него при запуске CLI —
  одна и та же JVM локально и на CI, системная java в golden больше не участвует.
  Продуктовый код не меняется (`JAVA_HOME`-приоритет уже есть в jre-resolution).
- Тест идемпотентности (тёплый кэш `.c4builder.cache`) остаётся только для `default` —
  кэш-механика одна на все варианты, время CI не утраиваем.
- CI: артефакт `golden-actual` включает все варианты; setup-java остаётся только как
  среда для `jre install` (не как источник JVM рендера).
- Онлайн-рендер (`generateLocalImages=false`) сознательно **не** покрывается:
  путь помечен на удаление (решение июля 2026).

## Capabilities

### New Capabilities

— нет.

### Modified Capabilities

- `regression-testing`:
  - golden-сборка расширяется с одного конфига до матрицы вариантов (требование
    «Golden-сборка fixture соответствует эталону» и устройство эталона);
  - требование воспроизводимости усиливается: вместо «одинаковой мажорной версии JDK»
    — пин конкретной managed-JVM через кеш jre-резолвера (`JAVA_HOME`).

## Impact

- Код: только тестовая обвязка и CI — `test/helpers.mjs`, `test/golden.test.mjs`,
  fixture-конфиги (`test/fixtures/*.c4builder.json`), `test/golden/**`
  (реорганизация + новые эталоны), `test/README.md`, `.github/workflows/ci.yml`.
- Продуктовый код и публичное поведение CLI не меняются.
- Время golden-джобы растёт ~×3 (три сборки fixture); смягчение — идемпотентность
  только на `default`.
- Первый прогон на новой машине скачивает Temurin JRE с Adoptium (допущение о
  доступности Adoptium уже зафиксировано в change `jre-resolver`); в CI кеш
  прогревается шагом `c4builder jre install --force` и кешируется между запусками.

## design

[Обзор](#C4-Builder)

# design — golden-matrix

## Context

Golden-обвязка (`test/helpers.mjs`, `test/golden.test.mjs`) собирает копию
`template/src` реальным CLI с одним конфигом `test/fixture.c4builder.json` и
сверяет дерево `docs/` с эталоном `test/golden/{manifest.json,tree/}`. Константы
`FIXTURE_CONFIG`, `GOLDEN_DIR`, `ACTUAL_DIR` — жёсткие, один вариант.

JVM для рендера берётся «системная» (`detectSystemJava`: `JAVA_HOME` → `PATH`,
мажор ≥17). На CI это Temurin 21 из setup-java, локально — что стоит у
разработчика (на Arch — дистрибутивная сборка OpenJDK с системным freetype).
Разные растеризаторы/метрики шрифта → разные `textLength` в SVG → периодические
ложные диффы эталона, хотя мажор JDK совпадает.

Это звено 0 цепочки TS-порта: расширенная сетка должна встать ДО рефакторинга
compose-слоя (`build.js`).

## Goals / Non-Goals

**Goals:**
- Зафиксировать эталоном ветки compose-слоя: `includeLinkToDiagram`,
  `diagramsOnTop`, `excludeOtherFiles`, `embedDiagram`, png-растеризация (resvg + ditaa).
- Устранить зависимость golden от локальной JVM: одна пиновая managed-JVM везде.
- Сохранить рабочий процесс: `npm test`, `test:golden`, `test:golden:update`
  работают как раньше, но покрывают все варианты.

**Non-Goals:**
- Онлайн-рендер (`generateLocalImages=false`) — путь под удаление, эталоном не фиксируем.
- Изменения продуктового кода (build.js, jre.js) — ноль правок.
- Полная комбинаторика опций — берём три осмысленных профиля, не 2^n.
- Тест wizard'а и `--site`/`--watch` — вне объёма (позже, в звеньях TS-порта).

## Decisions

### D1. Три варианта матрицы, одни исходники

| Вариант | Отличия от default | Что фиксирует |
|---|---|---|
| `default` | текущий fixture-конфиг | базовый контракт (как сейчас) |
| `links-top` | `includeLinkToDiagram=true`, `diagramsOnTop=true`, `excludeOtherFiles=true`, `includeNavigation=false`, `includeTableOfContents=false`, `includeBreadcrumbs=false` | ветку «ссылка вместо картинки», порядок диаграмм, исключение прочих файлов, отсутствие chrome-блока |
| `embed-png` | `embedDiagram=true`, `diagramFormat=png` | resvg-растеризацию (PlantUML+D2), нативный ditaa-PNG, base64-встраивание |

Каждый вариант — отдельный JSON в `test/fixtures/<variant>.c4builder.json`
(текущий `test/fixture.c4builder.json` переезжает в `test/fixtures/default.c4builder.json`).
`links-top` инвертирует все булевы переключатели default'а — две точки на каждую
ветку if/else compose-слоя. Детерминизм png: resvg пинован (2.6.2), шрифты
вендорные (`loadSystemFonts:false`), ditaa-PNG воспроизводим (уже в эталоне).

Альтернатива «отдельные исходники на вариант» отвергнута: одни исходники — один
дифф при правке `template/src`, меньше сущностей.

### D2. Раскладка эталона: `test/golden/<variant>/`

`test/golden/default/{manifest.json,tree/}`, `.../links-top/`, `.../embed-png/`.
Хелперы параметризуются вариантом (`goldenDir(variant)` и т.п.), `ACTUAL_DIR` →
`test/.tmp/actual/<variant>/`. `UPDATE_GOLDEN=1` перегенерирует все варианты за
один прогон (частичное обновление не нужно — сборки всё равно идут все).

Миграция: старые `test/golden/{manifest.json,tree}` удаляются в этом же PR,
эталоны всех вариантов генерируются заново (то же содержимое default, новый путь).

### D3. Пин JVM через кеш jre-резолвера, без правок продуктового кода

Тест-хелпер перед первой сборкой резолвит managed-JVM:

```js
import { cachedJava, resolveJava } from '../jre.js';
const jre = cachedJava() ?? (await resolveJava({ force: true })); // force ⇒ мимо системной
const javaHome = path.dirname(path.dirname(jre.path));            // <root>/bin/java → <root>
```

и передаёт `env: { ...process.env, JAVA_HOME: javaHome }` в `spawnSync` CLI.
`detectSystemJava` проверяет `JAVA_HOME` первым → рендер гарантированно идёт на
кешированном Temurin 21 (одна и та же сборка Adoptium с вшитым freetype локально
и на CI). Правок jre.js не нужно: `cachedJava`/`resolveJava` уже экспортируются.

Альтернативы: env-флаг `C4BUILDER_JRE_MODE=managed` в продуктовом коде (лишняя
поверхность ради тестов); docker-обёртка для локального прогона (тяжело, но
остаётся как escape hatch — см. Risks).

### D4. CI: прогрев кеша JRE + кеш между запусками

Шаг `node index.js jre install --force` до `npm test` (сеть под контролем,
таймауты теста не тратятся на скачивание) + `actions/cache` на
`~/.cache/c4builder/jre` с ключом от `TEMURIN_FEATURE`. setup-java остаётся
(vitest-юнитам jre.js нужна системная java для веток detectSystemJava), но
golden от него больше не зависит.

### D5. Идемпотентность — только `default`

Тест тёплого кэша (`.c4builder.cache`, второй прогон) остаётся на `default`:
механика чексумм одна на все варианты, а каждая лишняя сборка — десятки JVM-спавнов.

## Risks / Trade-offs

- [Кеш-чексумма не зависит от формата вывода] Варианты работают в изолированных
  временных директориях со своими `.c4builder.cache` → взаимного влияния нет.
- [Время CI ×3] Приемлемо (сборка fixture ~десятки секунд); смягчение — D5 и
  параллельность vitest на уровне файлов: каждый вариант — свой тест-файл или
  `describe.concurrent` не используем, оставляем последовательный прогон ради
  предсказуемости логов. Если станет больно — режем матрицу CI по node.
- [embed-png эталон бинарнее: PNG хранится только sha в manifest] Дифф по PNG
  нечитаем — но задача сетки «поймать расхождение», а не объяснить его; SVG-до-
  растеризации покрыт другими вариантами. Base64 в md — текстовый, диффуемый.
- [Adoptium недоступен в среде запуска] Тогда golden не прогонится — поведение
  честное (ошибка резолва с понятным сообщением от jre-resolver). Escape hatch:
  локальный docker-прогон образа CI; отдельный скрипт не заводим, пока не понадобился.
- [jre.js — CJS, тесты — ESM] `import ... from '../jre.js'` работает (Node CJS-
  interop для named exports через cjs-module-lexer — статический module.exports).

## Migration Plan

1. Хелперы: параметризация вариантом + пин JAVA_HOME (тесты ещё на старом эталоне default).
2. Новые fixture-конфиги + перенос текущего в `test/fixtures/default.c4builder.json`.
3. `UPDATE_GOLDEN=1` — генерация трёх эталонов, коммит вместе с удалением старого пути.
4. CI: шаг прогрева JRE + actions/cache + пути артефактов.
5. `test/README.md` — матрица, пин JVM, процедура обновления эталона.

Откат: revert PR (эталон и обвязка самодостаточны, продуктовый код не тронут).

## Open Questions

— нет (все решения зафиксированы выше; матрица расширяема новыми вариантами
по мере надобности, напр. под будущий TeaVM-флаг).

## tasks

[Обзор](#C4-Builder)

# tasks — golden-matrix

## 1. Пин managed-JVM в golden-обвязке

- [x] 1.1 `test/helpers.mjs`: хелпер `ensureManagedJre()` — `cachedJava() ?? resolveJava({ force: true })` из `jre.js`, вычислить `JAVA_HOME` (`<root>` из `<root>/bin/java`), закешировать на прогон
- [x] 1.2 `runBuild`: передавать `env` с подставленным `JAVA_HOME` managed-JRE в `spawnSync`
- [x] 1.3 Проверить локально: golden проходит на машине, где системная java ≠ Temurin (или с временно скрытой java в PATH) — механизм подтверждён (рендер на managed-JRE через `JAVA_HOME` без системной java в PATH); остаточное расхождение `class.svg`/`ditaa.png` — OS-font, задокументировано в README

## 2. Матрица fixture-конфигураций

- [x] 2.1 Создать `test/fixtures/`: перенести `test/fixture.c4builder.json` → `test/fixtures/default.c4builder.json`
- [x] 2.2 Добавить `test/fixtures/links-top.c4builder.json` (includeLinkToDiagram, diagramsOnTop, excludeOtherFiles = true; navigation/TOC/breadcrumbs = false)
- [x] 2.3 Добавить `test/fixtures/embed-png.c4builder.json` (embedDiagram = true, diagramFormat = png)
- [x] 2.4 `test/helpers.mjs`: параметризовать вариантом (`createFixture(variant)`, `goldenDir(variant)`, `actualDir(variant)`, `updateGolden(tree, variant)`, `compareWithGolden(tree, variant)`)

## 3. Тесты по матрице

- [x] 3.1 `test/golden.test.mjs`: цикл по вариантам — сборка, сравнение с эталоном варианта, запись actual по вариантам
- [x] 3.2 Сохранить контентные проверки default (stdlib/iuml SVG, кириллица, D2) как сейчас
- [x] 3.3 Добавить контентные проверки `links-top`: ссылки вместо `![diagram]`, диаграммы перед текстом, отсутствие скопированных «прочих» файлов и chrome-блока
- [x] 3.4 Добавить контентные проверки `embed-png`: `.png`-выходы вместо `.svg` (кроме vendor), `data:image/png;base64` в md, ditaa-PNG на месте
- [x] 3.5 Тест тёплого кэша — только вариант `default`

## 4. Эталоны

- [x] 4.1 `UPDATE_GOLDEN=1`: сгенерировать `test/golden/{default,links-top,embed-png}/`, удалить старые `test/golden/{manifest.json,tree/}` — старый эталон удалён; эталоны трёх вариантов сняты с CI (артефакт `golden-actual-node22`, прогон 28750752826) — канон CI, т.к. Arch расходится по `class.svg`/`ditaa.png`, а CI-байты бинарников невосстановимы локально
- [x] 4.2 Просмотреть дифф эталонов: default идентичен старому (только путь), в links-top/embed-png ветки видны глазами — проверено на локально сгенерированных эталонах: default байт-в-байт совпал со старым, кроме `class.svg` (форма глифов) и `ditaa.png` (нативный PNG); ветки links-top/embed-png подтверждены контентными проверками (7/7 зелёных)

## 5. CI и документация

- [x] 5.1 `.github/workflows/ci.yml`: шаг `node index.js jre install --force` до `npm test` + `actions/cache` на `~/.cache/c4builder/jre` (ключ от `TEMURIN_FEATURE` и os/arch)
- [x] 5.2 Проверить упаковку артефакта: `test/.tmp/actual/<variant>/` попадают в `golden-actual.tar.gz` — по построению (`writeActualTree` пишет в `test/.tmp/actual/<variant>/`, шаг `tar -C test/.tmp actual` пакует весь каталог)
- [x] 5.3 `test/README.md`: матрица вариантов, пин JVM (как и зачем), обновлённая процедура регенерации эталона
- [x] 5.4 Прогнать CI на ветке: golden зелёный на node 22 и 24, время джобы приемлемо — прогон 28750826914 (PR #8) зелёный: lint + test(node22) + test(node24); весь прогон 74 с (test-джобы ~65–71 с на трёх вариантах, JRE из кеша)

## specs

[Обзор](#C4-Builder)

- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-golden-matrix/specs/regression-testing/regression-testing)

## regression-testing

[Обзор](#C4-Builder)

# regression-testing — delta (golden-matrix)

## MODIFIED Requirements

### Requirement: Golden-сборка fixture соответствует эталону
Тестовый набор SHALL собирать fixture-проект «мини-arch» реальным запуском CLI (неинтерактивно, с готовым `.c4builder`) во временной директории для каждого варианта матрицы конфигураций и сравнивать полное дерево выходных файлов (site, md, complete-md, диаграммы) с закоммиченным эталоном этого варианта (`test/golden/<variant>/`). Сравнение MUST выполняться после нормализации (удаление XML-комментариев из SVG, приведение переводов строк к LF) и MUST включать идентичность списка файлов. Варианты MUST собираться из одних и тех же исходников `template/src`; различаются только fixture-конфиги (`test/fixtures/<variant>.c4builder.json`).

#### Scenario: Совпадение с эталоном
- **WHEN** golden-тест запускает сборку fixture варианта и выход совпадает с эталоном этого варианта после нормализации
- **THEN** тест варианта проходит

#### Scenario: Расхождение с эталоном
- **WHEN** содержимое хотя бы одного выходного файла или сам список файлов отличается от эталона варианта
- **THEN** тест падает с диффом, указывающим вариант, конкретные файлы и расхождения

#### Scenario: Изоляция вариантов
- **WHEN** собираются несколько вариантов матрицы
- **THEN** каждый вариант работает в отдельной временной директории со своим `.c4builder` и `.c4builder.cache`, не влияя на выход других вариантов

### Requirement: Fixture — демо-шаблон проекта
Fixture'ом golden-теста SHALL служить существующий демо-шаблон `template/src` (stdlib-инклюды, локальный `.iuml`, `.d2` с импортом, кириллица). Тест-хелпер MUST копировать шаблон во временную директорию и класть готовый `.c4builder` выбранного варианта из `test/fixtures/<variant>.c4builder.json`. Вариант `default` MUST сохранять текущий контракт: `diagramFormat=svg`, `generateLocalImages=true`, выходы site/md/complete-md, navigation/TOC/breadcrumbs.

#### Scenario: Сборка fixture из шаблона
- **WHEN** golden-тест собирает копию шаблона с конфигом варианта `default`
- **THEN** в выходе присутствуют SVG для stdlib-диаграмм и для диаграмм с `.iuml`-инклюдом, а кириллица сохранена в выходных md и SVG

### Requirement: Повторная сборка с кэшем идентична первой
Повторный запуск сборки в той же рабочей директории (с наполненным `.c4builder.cache`) SHALL давать дерево выходных файлов, идентичное первому прогону. Проверка выполняется на варианте `default` (механика кэша едина для всех вариантов).

#### Scenario: Второй прогон с тёплым кэшем
- **WHEN** сборка fixture варианта `default` выполняется второй раз без изменения исходников
- **THEN** выходное дерево байт-в-байт (после нормализации) совпадает с результатом первого прогона

### Requirement: Эталон обновляется только явной командой
Перезапись эталонных деревьев MUST происходить только при явном запуске режима обновления (`UPDATE_GOLDEN=1` / npm-скрипт `test:golden:update`); режим обновления SHALL регенерировать эталоны всех вариантов матрицы за один прогон. Обычный запуск тестов MUST NOT изменять эталоны.

#### Scenario: Явное обновление эталона
- **WHEN** тесты запущены в режиме обновления эталона
- **THEN** эталонные деревья всех вариантов перезаписываются текущим нормализованным выходом сборки

#### Scenario: Обычный запуск не трогает эталон
- **WHEN** тесты запущены без режима обновления
- **THEN** файлы эталонов остаются неизменными независимо от результата сравнения

### Requirement: Golden-эталон воспроизводим независимо от машины
Golden-эталон SHALL быть детерминированным и не зависеть от установленного на машине окружения. Рендер PlantUML в golden-прогонах MUST выполняться на пиновой managed-JVM из кеша jre-резолвера (Temurin, версия `TEMURIN_FEATURE`), а не на произвольной системной java: тест-хелпер резолвит кешированный JRE (при отсутствии — скачивает, минуя системную java) и передаёт его через `JAVA_HOME` запускаемому CLI. Раскладка считается Java-движком Smetana, шрифт диаграмм — вендорный; внешний graphviz не участвует. Регенерация эталона на разных машинах MUST давать идентичное дерево выходов.

#### Scenario: Регенерация на разных машинах
- **WHEN** эталон регенерируется на двух машинах с одним вендорным JAR/шрифтом
- **THEN** golden-сборка обеих машин идёт на одной и той же managed-JVM из кеша jre-резолвера и нормализованное дерево выходов идентично

#### Scenario: Локальный прогон совпадает с CI
- **WHEN** разработчик запускает `npm test` локально
- **THEN** golden-тест проходит без расхождений с эталоном, снятым на CI, независимо от того, какая системная java установлена локально

#### Scenario: Managed-JRE отсутствует и не скачивается
- **WHEN** кеш jre-резолвера пуст и скачивание JRE недоступно (нет сети/Adoptium)
- **THEN** golden-тест падает с понятной ошибкой резолва JRE, а не молча использует системную java

## ADDED Requirements

### Requirement: Матрица вариантов фиксирует ветки compose-слоя
Golden-матрица SHALL включать, помимо `default`, варианты, фиксирующие альтернативные ветки формирования выхода: `links-top` (`includeLinkToDiagram=true`, `diagramsOnTop=true`, `excludeOtherFiles=true`, navigation/TOC/breadcrumbs выключены) и `embed-png` (`embedDiagram=true`, `diagramFormat=png`). Эталоны вариантов MUST фиксировать соответствующее поведение: ссылки вместо изображений и порядок «диаграммы перед текстом» (`links-top`); PNG-выход растеризацией resvg для PlantUML/D2, нативный ditaa-PNG и base64-встраивание диаграмм в md (`embed-png`).

#### Scenario: links-top — ссылки вместо картинок, диаграммы сверху
- **WHEN** собирается вариант `links-top`
- **THEN** в md-выходах диаграммы представлены ссылками (не `![diagram](...)`-изображениями), блоки диаграмм стоят перед текстом, прочие файлы (не md/puml/d2) в выход не копируются, а navigation/TOC/breadcrumbs отсутствуют

#### Scenario: embed-png — растеризация и встраивание
- **WHEN** собирается вариант `embed-png`
- **THEN** не-ditaa диаграммы (PlantUML и D2) присутствуют в выходе как PNG, полученные растеризацией SVG, ditaa — как нативный PNG, а в md-файлах диаграммы встроены как `data:image/png;base64,…`

#### Scenario: Правка compose-логики ломает соответствующий вариант
- **WHEN** поведение ветки, зафиксированной вариантом (напр. формат ссылки на диаграмму), изменено в коде без обновления эталона
- **THEN** golden-тест соответствующего варианта падает

## 2026-07-05-dev-toolchain

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-05 · **Tasks:** <progress value="13" max="13"></progress> 13/13 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/specs/specs)

# dev-toolchain — Biome, lint-джоба CI, гигиена package.json

## Why

Стартовое звено перехода на современный стек (решения explore-сессии 2026-07-05:
Biome 2, далее tsc → dist/ и порт на TS). Прежде чем трогать код, нужна планка
качества, которая держится автоматически: единый линтер/форматтер и CI-джоба,
падающая на нарушениях. Сейчас в репо нет ни линтера, ни формат-контроля, стиль
исторически разнородный, а npm-пакет публикует всё дерево репозитория
(в `package.json` нет `files` — в пакет попадают openspec/, docs/, test/).

## What Changes

- **Biome 2** как единственный линтер и форматтер (devDependency, пин версии):
  - `biome.json`: форматтер настраивается под существующий стиль кода
    (4 пробела, одинарные кавычки, ширина ~110), чтобы дифф форматирования был минимален;
  - линт от `recommended`; правила, требующие рефакторинга, точечно отключаются
    с комментарием — включим в звеньях TS-порта;
  - ignore: `vendor/`, `template/`, `docs/`, `test/golden/`, `node_modules/`
    (вендорное, пользовательский контент fixture и эталоны не форматируем).
- Форматирование всего репо — отдельным коммитом (без ручных правок в нём).
- Тривиальные автофиксы линта отдельным коммитом, каждый — без изменения
  поведения (напр. мёртвый импорт `joi` в build.js:32, `new Buffer.from` →
  `Buffer.from` в utils.js:63). Golden остаётся зелёным.
- npm-скрипты: `lint` (проверка), `lint:fix`, `format` (запись), `check` (biome ci).
- **CI**: отдельная быстрая джоба `lint` в `ci.yml` (biome ci, без Java и матрицы).
- **package.json**:
  - `files`-whitelist: в npm-пакет попадают только код CLI, `template/`, `vendor/`, README;
  - `engines.node >= 20.19` (решение explore-сессии; Docker-образ на node:24 —
    в звене scaffold, где появится build-стадия).

Не входит (следующие звенья): tsconfig/tsc, `src/`-раскладка, ESM, переименования
файлов, апгрейды зависимостей.

## Capabilities

### New Capabilities

- `dev-toolchain`: линт и формат кодовой базы — единый инструмент (Biome),
  конфигурация, npm-скрипты, зона покрытия (что игнорируется и почему),
  требования к составу npm-пакета (`files`) и минимальной версии Node (`engines`).

### Modified Capabilities

- `ci-validation`: workflow дополняется lint-джобой — нарушение линта/формата
  даёт красный статус PR наравне с тестами.

## Impact

- Новые файлы: `biome.json`; правки: `package.json` (devDependency, scripts,
  files, engines), `.github/workflows/ci.yml` (джоба lint).
- Один крупный формат-коммит по всем *.js/*.mjs/*.json репо (кроме ignore-зон).
- Поведение CLI не меняется: golden-тест зелёный до и после каждого коммита звена.
- Потребители пакета: npm-пакет худеет (files), установка на Node <20.19 начнёт
  предупреждать/падать при engine-strict — осознанное решение (Node 20 EOL).

## design

[Обзор](#C4-Builder)

# design — dev-toolchain

## Context

Кодовая база: 15 плоских CJS-файлов (~2 600 LOC) + ESM-тесты, без линтера и
форматтера. Впереди цепочка TS-порта (scaffold src/dist → порт по кластерам);
это звено ставит инструментальную планку до любых правок кода. Решения
explore-сессии: Biome 2 (один инструмент вместо ESLint+Prettier), npm остаётся,
engines >=20.19. Страховка поведения — golden-тест (после звена golden-matrix —
три варианта + пин JVM).

## Goals / Non-Goals

**Goals:**
- Один инструмент на линт+формат, один конфиг, быстрые локальные команды.
- CI падает на нарушениях — планка держится без дисциплины.
- Минимальный осмысленный дифф форматирования (конфиг под текущий стиль).
- Гигиена пакета: `files`, `engines`.

**Non-Goals:**
- TypeScript, tsconfig, src/-раскладка, ESM — следующее звено (scaffold).
- Массовые правки кода под линт — только тривиальные автофиксы без изменения
  поведения; остальное — точечные отключения правил с комментарием.
- Правки Dockerfile (base image поднимем в scaffold, где появится build-стадия).
- pre-commit hooks (husky и т.п.) — не заводим, планку держит CI.

## Decisions

### D1. Biome 2, пин версии

`@biomejs/biome` в devDependencies с точной версией (без `^`): формат/линт
должны быть воспроизводимы в CI и локально байт-в-байт. Апгрейды Biome —
осознанные коммиты (перегенерация формата в том же PR).

Альтернативы: ESLint 9 + Prettier (богаче type-aware правила — станут
актуальны после TS-порта, тогда и пересмотрим; сейчас два инструмента и два
конфига против одного) — отвергнуто решением сессии; oxlint — моложе, без
форматтера.

### D2. Конфиг под существующий стиль

`biome.json`: indentStyle=space, indentWidth=4, quoteStyle=single,
lineWidth=110, semicolons=always, trailingComma по факту преобладающего стиля.
Цель — формат-коммит меняет минимум строк, git blame страдает точечно
(при желании след формат-коммита прячется через `.git-blame-ignore-revs`).

Линт: `recommended` как база. Ожидаемые конфликты на легаси-коде — политика:
- тривиальный безопасный автофикс (мёртвый импорт, `new Buffer.from(s)` →
  `Buffer.from(s)` — семантика идентична: `new (Buffer.from)(s)` возвращает
  тот же объект) — чинится в этом звене, отдельным коммитом;
- всё, что требует переписывания логики (например, implicit-глобал `responses`
  в cli.collect.js — известный дефект, уйдёт в звене порта wizard) — правило
  локально `// biome-ignore` с пометкой `TODO(ts-port)` либо выключено в
  конфиге с комментарием-причиной.

### D3. Зоны игнора

`vendor/` (чужой код и шрифты), `template/` (пользовательский контент — он же
исходники golden-fixture: формат сломает эталоны!), `docs/`, `test/golden/`
(эталоны), `test/.tmp/`. Всё остальное — js/mjs/json — под Biome.

### D4. CI: отдельная джоба lint

В `ci.yml` добавляется джоба `lint` вне node-матрицы: checkout → setup-node
(24) → `npm ci --ignore-scripts` → `npx biome ci .`. Без Java: линт не зависит
от рендера, падает за секунды. Тестовая джоба не меняется. `biome ci` проверяет
и линт, и формат (diff-режим, без записи).

### D5. package.json: files и engines

- `files`: `index.js`, `cli*.js`, `build.js`, `utils.js`, `defaults.js`,
  `d2renderer.js`, `pngraster.js`, `jre.js`, `docsify.template.js`,
  `template/`, `vendor/`, `README.MD`, `license` (bin и package.json npm кладёт
  всегда). Проверка — `npm pack --dry-run` до/после: из пакета уходят
  openspec/, docs/, test/, Dockerfile, конфиги CI.
- `engines.node: ">=20.19"` — без `engine-strict` это предупреждение, не
  блокер; фиксирует поддерживаемый диапазон перед ESM/TS-звеньями.

## Risks / Trade-offs

- [Формат-коммит зашумляет blame] → конфиг под текущий стиль (минимум правок) +
  один изолированный коммит, hash — в `.git-blame-ignore-revs`.
- [Автофикс незаметно меняет поведение] → политика D2: только доказуемо
  эквивалентные правки, по коммиту на смысловую группу, golden после каждого.
- [Biome-format для JSON заденет форматирование package.json/манифестов]
  → test/golden в ignore; package.json Biome форматирует — допустимо (не
  публикуемый байт-контракт).
- [files-whitelist забудет нужный файл — сломанный пакет] → `npm pack
  --dry-run` в чеклисте задач + smoke-установка пакета из tarball и запуск
  `--help`/`new -y` перед мержем.

## Migration Plan

Порядок коммитов внутри PR (каждый — golden зелёный):
1. `biome.json` + devDependency + npm-скрипты (кода не трогает);
2. формат-коммит (`biome format --write`), без ручных правок;
3. тривиальные lint-автофиксы + точечные ignore/off с комментариями;
4. CI-джоба lint;
5. `files` + `engines` в package.json (+ `npm pack --dry-run` проверка).

Откат: revert PR целиком — кода поведение не меняло.

## Open Questions

— нет.

## tasks

[Обзор](#C4-Builder)

# tasks — dev-toolchain

## 1. Biome: конфиг и скрипты

- [x] 1.1 `@biomejs/biome` в devDependencies (точная версия, без `^`)
- [x] 1.2 `biome.json`: форматтер под текущий стиль (space/4, single quotes, semicolons, lineWidth 110), линт `recommended`, ignore-зоны (`vendor/`, `template/`, `docs/`, `test/golden/`, `test/.tmp/`)
- [x] 1.3 npm-скрипты: `lint`, `lint:fix`, `format`, `check` (biome ci)
- [x] 1.4 Прогнать `npm run lint` — инвентаризация нарушений: список «тривиальный автофикс» vs «ignore/off с комментарием»

## 2. Приведение репо

- [x] 2.1 Формат-коммит: `biome format --write` без ручных правок; убедиться, что `template/`, `vendor/`, `test/golden/` не тронуты; hash коммита — в `.git-blame-ignore-revs`
- [x] 2.2 Тривиальные lint-автофиксы отдельным коммитом (мёртвый импорт joi в build.js, `new Buffer.from` → `Buffer.from` в utils.js и подобное) — только доказуемо эквивалентные правки
- [x] 2.3 Остальные нарушения: точечные `biome-ignore` с `TODO(ts-port)` либо off в конфиге с причиной; `npm run check` — чисто
- [x] 2.4 `npm test` (golden + юниты) зелёный после каждого из коммитов 2.1–2.3

## 3. CI

- [x] 3.1 Джоба `lint` в `.github/workflows/ci.yml`: checkout → setup-node 24 → `npm ci --ignore-scripts` → `npx biome ci .` (без Java, вне матрицы)
- [x] 3.2 Проверить на ветке: джоба падает на нарочно испорченном формате, проходит после фикса

## 4. Гигиена package.json

- [x] 4.1 `files`-whitelist (js-модули CLI, `template/`, `vendor/`, README, license); сверка `npm pack --dry-run` до/после
- [x] 4.2 `engines.node: ">=20.19"`
- [x] 4.3 Smoke: установить пакет из tarball (`npm pack` → `npm i -g ./…tgz` или в tmp-префикс), проверить `c4builder --help` и `c4builder --new --name demo -y` + сборку созданного проекта

## specs

[Обзор](#C4-Builder)

- [ci-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/specs/ci-validation/ci-validation)
- [dev-toolchain](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-dev-toolchain/specs/dev-toolchain/dev-toolchain)

## ci-validation

[Обзор](#C4-Builder)

# ci-validation — delta (dev-toolchain)

## ADDED Requirements

### Requirement: Линт и формат проверяются на CI
Workflow CI SHALL содержать отдельную джобу `lint` (вне node-матрицы, без установки Java), выполняющую проверку линта и формата пинованной версией Biome (`biome ci`). Нарушение линта или формата MUST приводить к красному статусу проверки PR наравне с падением тестов.

#### Scenario: Нарушение формата в PR
- **WHEN** в PR попадает файл, не соответствующий сконфигурированному формату или правилам линта
- **THEN** джоба `lint` завершается с ненулевым кодом и PR получает failed-статус

#### Scenario: Линт не тянет тяжёлое окружение
- **WHEN** выполняется джоба `lint`
- **THEN** среди её шагов нет установки Java и запуска тестов — только checkout, setup-node, установка зависимостей и `biome ci`

## dev-toolchain

[Обзор](#C4-Builder)

# dev-toolchain — delta (dev-toolchain)

## ADDED Requirements

### Requirement: Единый линтер и форматтер
Репозиторий SHALL использовать Biome (пин точной версии в devDependencies) как единственный линтер и форматтер JS/JSON-кода. Конфигурация `biome.json` MUST соответствовать существующему стилю кода (отступ 4 пробела, одинарные кавычки, точки с запятой, ширина строки ~110), а линт MUST базироваться на наборе `recommended`; отключение правила или локальный `biome-ignore` MUST сопровождаться комментарием-причиной.

#### Scenario: Локальная проверка
- **WHEN** разработчик запускает `npm run lint` (или `npm run check`)
- **THEN** Biome проверяет линт и формат всех файлов вне ignore-зон и завершается ненулевым кодом при нарушениях

#### Scenario: Автоформатирование
- **WHEN** разработчик запускает `npm run format`
- **THEN** Biome приводит файлы к сконфигурированному стилю на месте

#### Scenario: Воспроизводимость версии
- **WHEN** линт/формат запускаются локально и в CI
- **THEN** используется одна и та же пинованная версия Biome и результат идентичен

### Requirement: Зоны, свободные от линта и форматирования
Конфигурация MUST исключать из обработки Biome: `vendor/` (сторонний код и шрифты), `template/` (пользовательский контент, он же исходники golden-fixture), `docs/`, `test/golden/` (эталоны), `test/.tmp/`, `node_modules/`. Форматирование этих зон MUST NOT происходить даже при `npm run format`.

#### Scenario: Эталоны и шаблон не переформатируются
- **WHEN** выполняется `npm run format` по всему репозиторию
- **THEN** файлы в `template/`, `vendor/`, `test/golden/` остаются байт-в-байт неизменными, golden-тест проходит без регенерации эталона

### Requirement: Состав npm-пакета ограничен whitelist'ом
`package.json` MUST содержать `files`-whitelist, включающий только код CLI (js-модули корня), `template/`, `vendor/`, README и лицензию. Служебные директории репозитория (openspec/, docs/, test/, CI-конфиги, Dockerfile) MUST NOT попадать в публикуемый пакет. Опубликованный пакет MUST оставаться работоспособным: `c4builder --help` и `c4builder new` с шаблоном и вендорными ресурсами работают из установленного пакета.

#### Scenario: Проверка состава пакета
- **WHEN** выполняется `npm pack --dry-run`
- **THEN** в списке файлов пакета присутствуют js-модули CLI, `template/`, `vendor/`, README и отсутствуют openspec/, docs/, test/, Dockerfile

#### Scenario: Smoke-проверка установленного пакета
- **WHEN** пакет из tarball устанавливается в чистую директорию и запускается `c4builder --help` и неинтерактивный `c4builder --new --name demo -y`
- **THEN** команды завершаются успешно, проект создаётся из шаблона

### Requirement: Минимальная поддерживаемая версия Node зафиксирована
`package.json` MUST декларировать `engines.node: ">=20.19"`. Код и зависимости в пределах цепочки модернизации MUST NOT требовать возможностей Node, отсутствующих в 20.19.

#### Scenario: Установка на устаревшем Node
- **WHEN** пакет устанавливается на Node ниже 20.19
- **THEN** npm сообщает о несовместимости engines (предупреждение, либо отказ при engine-strict)

## 2026-07-05-d2-backend

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-04 · **Tasks:** <progress value="16" max="16"></progress> 16/16 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/tasks/tasks) · [README](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/README/README) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/specs/specs)

# D2 как второй бэкенд рендера

## Why

Сейчас c4builder рендерит только PlantUML (`.puml`). Единственный движок — это
и потолок выразительности, и точка отказа. D2 (terrastruct) даёт то, чего у
PlantUML нет: модульную систему (imports + classes + vars), тонкий контроль
раскладки (dagre/elk, grid-режим), человечный синтаксис — при этом **тоже
поддерживает C4** (официально: `shape: c4-person`, `suspend` для views). Два
движка рядом — это и запас выразительности под конкретные задачи, и хеджирование.

Ключевой барьер снят спайками (см. design): D2 идёт через `@terrastruct/d2`
(**WASM → SVG**), без внешних бинарей — как и вся линия модернизации («ноль
внешних зависимостей»: убрали graphviz, D2 не возвращает системную зависимость).
Паритет с `.iuml` подтверждён: импорты D2 резолвятся через виртуальную файловую
систему API, C4-цвета из общего `c4lib.d2` применяются, кириллица цела, выход
детерминирован байт-в-байт со вшитыми шрифтами.

## What Changes

- **`.d2`-файлы становятся первоклассным типом диаграмм** рядом с `.puml`. Рендер
  выбирается по расширению: `.puml` → PlantUML, `.d2` → D2. Существующие
  `.puml`-проекты (весь `arch`) не затрагиваются — изменение чисто аддитивное.
- **Диспетчер рендереров по расширению** в `build.js`: сбор дерева, генерация
  изображений и ссылки в markdown перестают быть завязаны на `.puml`.
- **Импорты D2 собирает сам c4builder** и подаёт движку через виртуальную `fs`
  (`compile({ fs, inputPath })`). Тот же разбор графа `@`/`...@`-импортов питает и
  чексумму кэша (как `foldIncludes` для `!include`), чтобы правка общего `c4lib.d2`
  инвалидировала зависимые диаграммы.
- **`@terrastruct/d2` — `optionalDependency` с ленивой загрузкой** (пакет ~60 МБ):
  тянется/инициализируется только когда в проекте есть `.d2`. Отсутствие пакета при
  наличии `.d2` — понятная ошибка с подсказкой установки.
- **Демо-шаблон получает пример на D2**: `.d2`-диаграмма + общий `c4lib.d2`
  (аналог `styles.iuml`), чтобы шаблон-fixture покрывал оба бэкенда.
- **Golden-тест расширяется на D2** (детерминизм D2 — из коробки, vendored-шрифт не
  нужен). После рендера D2-инстанс явно завершается (webworker иначе держит процесс).

## Capabilities

### Modified Capabilities
- `diagram-rendering`: добавляется второй бэкенд (D2/WASM) с выбором по расширению,
  резолвингом импортов через виртуальную fs и опциональной ленивой зависимостью.
- `regression-testing`: golden-fixture и тесты покрывают D2-рендер наряду с PlantUML.

## Impact

- `build.js`: рендер-путь абстрагируется в диспетчер по расширению; добавляется
  D2-рендерер (сбор `fs`, `compile`/`render`, teardown воркера).
- `package.json`: `@terrastruct/d2` в `optionalDependencies`.
- `template/src`: пример `.d2` + `c4lib.d2`.
- `test/`: fixture и golden-эталон дополняются D2-выходом.
- Зависимость по времени: этот change следует за `plantuml-java-direct` (мультибэкенд
  опирается на его capability `diagram-rendering`) и предпочтительно за TS-портом
  (диспетчер рендереров чище на типах). Целевое состояние специфицируется здесь.
- Поведение существующих `.puml`-проектов не меняется.

## design

[Обзор](#C4-Builder)

# Design: d2-backend

## Context

c4builder рендерит только `.puml` через PlantUML; `.puml` захардкожен в `build.js`
в ~15 местах (`pumlFiles`, `isDitaa ? png : format`, `require('node-plantuml')`,
regex `.*\.puml`). Кэш диаграмм инвалидируется через `foldIncludes` — свёртку графа
`!include` в чексумму. Главный потребитель `arch` — целиком C4-PlantUML и на D2 не
мигрирует; D2 — для новых диаграмм и задач, где PlantUML тесен.

Место в цепочке: после `plantuml-java-direct` (даёт capability `diagram-rendering`
и мультибэкенд-развязку) и предпочтительно после TS-порта (типизированный реестр
рендереров). Целевой движок — `@terrastruct/d2` (WASM), согласовано в плане
модернизации.

## Спайки (проведены в explore, обосновывают решения)

1. **Паритет с `.iuml`.** `...@c4lib` (спред-импорт) вливает classes/vars из файла —
   C4-цвета применяются; partial `@file.key`; вложенные импорты; `shape: c4-person`
   и `suspend` присутствуют. C4 в D2 — официальная поддержка (доки D2, апрель 2025).
2. **WASM-импорты.** API `compile({ fs: Record<path,content>, inputPath, options })`
   принимает **виртуальную файловую систему словарём** — импорты резолвятся внутри
   WASM без доступа к диску. Проверено: многофайловый импорт через `fs` работает.
3. **Детерминизм.** Два прогона одной диаграммы → SVG байт-в-байт идентичны; шрифты
   вшиты в SVG (`@font-face` base64, дефолт Source Sans Pro), кириллица — текстом.
   Golden для D2 детерминирован без vendored-шрифта (контраст с PlantUML).
4. **Движки.** `layout: 'dagre'` (дефолт) и `'elk'` работают, дают разный layout;
   TALA (проприетарный) в WASM отсутствует — ожидаемо.
5. **Операционное.** compile+render ~0.3–0.6 с/диаграмма. D2.js использует webworker:
   после счёта процесс **не завершается**, пока воркер жив, — нужен явный teardown.
6. **Размер.** `@terrastruct/d2` ~60 МБ unpacked (WASM внутри).

## Goals / Non-Goals

**Goals:**
- `.d2` как первоклассный тип диаграмм рядом с `.puml`, выбор бэкенда по расширению.
- Импорты D2 (переиспользуемые стили/определения) работают через виртуальную fs.
- Golden покрывает D2; поведение `.puml`-проектов не меняется.

**Non-Goals:**
- Миграция `arch`/существующих диаграмм на D2 (остаются PlantUML).
- Автоконвертация `.puml` ↔ `.d2`.
- Полный порт C4-PlantUML stdlib в D2 (поставляем пример `c4lib.d2`, не весь stdlib).
- TALA-раскладка (недоступна в WASM).
- PNG для `.d2` — идёт общим путём SVG→resvg (отдельная фича), здесь не реализуется.

## Decisions

1. **Диспетчер рендереров по расширению.** Дерево собирает не `pumlFiles`, а
   обобщённые `diagrams[] { file, ext, content, engine }`; `engine` = `plantuml`
   (`.puml`, включая ditaa) | `d2` (`.d2`). `generateImages` диспетчеризует по
   `engine`; regex поиска диаграмм в md расширяется до `\.(puml|d2)`. Именование
   выхода — по имени файла (как сейчас), формат `.svg`.

2. **c4builder сам собирает `fs` для D2.** В отличие от PlantUML (JVM резолвит
   `!include` с диска), D2-рендерер парсит граф `@`/`...@`-импортов от `.d2`-файла,
   складывает `{ путь: контент }` и зовёт `compile({ fs, inputPath })`. Этот же
   парсер питает чексумму кэша — переиспользуем идею `foldIncludes`, меняется только
   синтаксис импортов. Alternative — предсклейка импортов в один текст: отвергнута
   (виртуальная fs нативна и сохраняет диагностику путей).

3. **Опциональная ленивая зависимость.** `@terrastruct/d2` в `optionalDependencies`,
   `require` — лениво, только если в дереве есть `.d2`. Нет пакета + есть `.d2` →
   явная ошибка со ссылкой на установку. Причина — вес ~60 МБ: не навязываем его
   тем, кто пользуется только PlantUML.

4. **Явный teardown воркера.** После завершения сборки D2-инстанс закрывается
   (terminate/`worker`), иначе CLI-процесс висит. Единый инстанс на прогон
   переиспользуется для всех `.d2` (warm-up один раз).

5. **Layout по умолчанию dagre, elk — опция.** Новый конфиг `d2Layout`
   (`dagre`|`elk`, дефолт `dagre`). Golden фиксирует конкретный движок.

6. **Golden D2 — из коробки.** Детерминизм обеспечен вшитым шрифтом; vendored-шрифт
   (как для PlantUML) не требуется. Fixture — `.d2`-пример в `template/src`.

## Risks / Trade-offs

- **[Вес +60 МБ]** — mitigated `optionalDependencies` + lazy-require; документируем.
- **[Дрейф детерминизма между версиями пакета]** — golden привязан к версии
  `@terrastruct/d2`; обновление версии = осознанная регенерация эталона (как с JAR).
- **[Webworker/среда]** — headless-запуск в CI и teardown проверяются golden-тестом
  (job не должен зависать); спайк показал корректный exit при явном завершении.
- **[Абстракция поверх CommonJS до TS-порта]** — если делать раньше TS, реестр
  рендереров пишется без типов. Приемлемо; при TS-порте реестр типизируется.
- **[Диагностический вывод/ошибки компиляции D2]** — ошибки `compile` (напр. битый
  импорт) пробрасываются понятным сообщением с путём файла.

## Open Questions

- Делать до или после TS-порта? Влияет на чистоту реестра рендереров, не на объём
  работы — решается при планировании порядка.
- Нужен ли выбор `d2Theme` в конфиге сразу или достаточно `d2Layout` на первом шаге.

## tasks

[Обзор](#C4-Builder)

# Tasks: d2-backend

## 1. Зависимость D2

- [x] 1.1 Добавить `@terrastruct/d2` в `optionalDependencies`; зафиксировать версию
- [x] 1.2 Ленивый `require` движка только при наличии `.d2` в дереве; при отсутствии
      пакета — понятная ошибка с подсказкой установки

## 2. Абстракция рендереров по расширению

- [x] 2.1 Обобщить сбор дерева: вместо `item.pumlFiles` — `item.diagrams[]`
      `{ file, ext, content, engine }`, `engine` = `plantuml` | `d2`
- [x] 2.2 Диспетчеризовать `generateImages` по `engine`; сохранить путь PlantUML
      (java-direct + Smetana) без изменений, включая ditaa
- [x] 2.3 Расширить regex поиска диаграмм в markdown до `\.(puml|d2)`; ссылки/имена
      выходов работают для обоих

## 3. D2-рендерер

- [x] 3.1 Парсер графа импортов `.d2` (`@`/`...@`): сбор `{ путь: контент }` для
      виртуальной `fs` + материал для чексуммы кэша (аналог `foldIncludes`)
- [x] 3.2 Рендер через `compile({ fs, inputPath, options })` → `render` → SVG;
      единый инстанс на прогон (warm-up один раз), конфиг `d2Layout` (dagre|elk)
- [x] 3.3 Явный teardown D2-инстанса (webworker) после сборки — процесс завершается
- [x] 3.4 Инвалидация кэша при правке импортируемого `.d2` (проверить свёртку графа)
- [x] 3.5 Проброс ошибок компиляции D2 понятным сообщением с путём файла

## 4. Шаблон и fixture

- [x] 4.1 Добавить в `template/src` пример `.d2`-диаграммы + общий `c4lib.d2`
      (аналог `styles.iuml`), с C4-классами и кириллицей
- [x] 4.2 Убедиться, что `.d2`/`c4lib.d2` попадают в git и в пакет, а выход — в dist

## 5. Golden и CI

- [x] 5.1 Расширить golden-fixture D2-диаграммой; нормализация покрывает D2-SVG
- [x] 5.2 Регенерировать эталон (`test:golden:update`), закоммитить; проверить
      детерминизм двух прогонов D2
- [x] 5.3 Прогнать CI: сборка с `.d2` проходит, процесс не виснет, эталон совпадает
      (локально подтверждено; в CI класс-диаграмма совпадёт на Temurin 21)

## 6. Документация

- [x] 6.1 README: как добавить `.d2`-диаграмму, установка опционального движка,
      импорты и общий `c4lib.d2`, выбор `d2Layout`

## README

[Обзор](#C4-Builder)

# d2-backend

D2 как второй бэкенд рендера диаграмм (@terrastruct/d2 WASM → SVG) рядом с PlantUML: .d2-файлы, импорты через виртуальную fs, C4-поддержка

## specs

[Обзор](#C4-Builder)

- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/specs/diagram-rendering/diagram-rendering)
- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-05-d2-backend/specs/regression-testing/regression-testing)

## diagram-rendering

[Обзор](#C4-Builder)

# diagram-rendering

## ADDED Requirements

### Requirement: Второй бэкенд рендера выбирается по расширению
Сборка SHALL поддерживать `.d2`-диаграммы наравне с `.puml` и выбирать движок
рендера по расширению файла: `.puml` — PlantUML, `.d2` — D2. Добавление D2 MUST NOT
менять поведение существующих `.puml`-проектов; выходной файл диаграммы именуется по
имени исходного файла, формат — SVG.

#### Scenario: Смешанное дерево .puml и .d2
- **WHEN** в дереве проекта присутствуют и `.puml`, и `.d2` файлы
- **THEN** `.puml` рендерятся PlantUML, `.d2` рендерятся D2, оба дают SVG рядом с
  прочими выходами, ссылки в markdown работают для обоих

#### Scenario: Проект только из .puml не затронут
- **WHEN** в проекте нет ни одного `.d2`-файла
- **THEN** сборка и её выход идентичны прежнему поведению, а зависимость D2 не
  загружается

### Requirement: Импорты D2 резолвятся через виртуальную файловую систему
D2-рендерер SHALL собирать граф импортов (`@`/`...@`) исходного `.d2`-файла и
передавать движку виртуальную файловую систему (`compile({ fs, inputPath })`), чтобы
переиспользуемые стили и определения из отдельных `.d2`-файлов применялись. Тот же
граф импортов MUST учитываться в чексумме кэша диаграмм: правка импортируемого файла
инвалидирует зависимые диаграммы.

#### Scenario: Общие стили через импорт
- **WHEN** `.d2`-диаграмма импортирует общий файл (`...@c4lib`) с classes/vars
- **THEN** импортируемые стили применяются в выходном SVG

#### Scenario: Правка импортируемого файла инвалидирует кэш
- **WHEN** изменён импортируемый `.d2`-файл, а сама диаграмма — нет
- **THEN** при следующей сборке зависимая диаграмма перерисовывается, а не берётся из кэша

### Requirement: Зависимость D2 опциональна и загружается лениво
Пакет движка D2 SHALL быть опциональной зависимостью и загружаться только при
наличии в проекте хотя бы одного `.d2`-файла. При наличии `.d2` и отсутствии пакета
сборка MUST завершаться понятной ошибкой с указанием, как установить зависимость.
После завершения рендера D2 ресурсы движка (webworker) MUST освобождаться, чтобы
процесс сборки корректно завершался.

#### Scenario: .d2 без установленного движка
- **WHEN** в проекте есть `.d2`, но пакет движка D2 не установлен
- **THEN** сборка падает с понятным сообщением и подсказкой установки, а не с
  невнятной ошибкой модуля

#### Scenario: Процесс завершается после сборки
- **WHEN** сборка с `.d2`-диаграммами завершена
- **THEN** CLI-процесс завершается и не остаётся висеть из-за незакрытого воркера

## regression-testing

[Обзор](#C4-Builder)

# regression-testing

## ADDED Requirements

### Requirement: Golden-тест покрывает D2-рендер
Golden-fixture SHALL включать `.d2`-диаграмму с импортом общего `.d2`-файла, а
golden-тест MUST сравнивать её SVG-выход с эталоном наравне с PlantUML-диаграммами.
Детерминизм D2-выхода обеспечивается вшитыми шрифтами и фиксированной версией пакета
движка; vendored-шрифт для D2 не требуется.

#### Scenario: D2-диаграмма в fixture совпадает с эталоном
- **WHEN** golden-тест собирает fixture, содержащий `.d2`-диаграмму с импортом
- **THEN** её SVG (после нормализации) совпадает с закоммиченным эталоном, а
  импортированные стили присутствуют в выходе

#### Scenario: Повторный прогон D2 идентичен
- **WHEN** сборка fixture с `.d2` выполняется дважды
- **THEN** SVG-выход D2-диаграммы байт-в-байт совпадает между прогонами

## 2026-07-04-template-offline

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-04 · **Tasks:** <progress value="7" max="7"></progress> 7/7 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-template-offline/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-template-offline/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-template-offline/specs/specs)

# Офлайн-шаблон демо-проекта

## Why

`c4builder new` сегодня генерит проект, который не собирается без интернета: все 6 C4-диаграмм шаблона тянут C4-PlantUML по URL с `raw.githubusercontent.com` (то же — в VS Code-сниппетах). В корпсреде это означает сломанное демо «из коробки». Кроме того, шаблон станет fixture для golden-теста (change `golden-test-ci`) — а fixture обязан собираться офлайн и детерминированно.

## What Changes

- Все `!include https://raw.githubusercontent.com/...` в `template/src/**/*.puml` (6 файлов) заменяются на stdlib-инклюды `!include <C4/...>` — C4-PlantUML вшит в PlantUML JAR, сеть не нужна.
- В демо добавляется пример локального `.iuml` (общие стили), подключаемого из диаграмм — паттерн, которым живёт главный потребитель (arch).
- В демо добавляется одна страница с кириллицей (md-текст + русские подписи в диаграмме) — демонстрация, что кириллица работает.
- `vendor/C4-PlantUML/C4.code-snippets` (5 URL-вхождений) переводится на stdlib-инклюды.
- Плейсхолдер `{{plantumlVersion}}` из puml-файлов шаблона исчезает; код подстановки в `cli.new.js` не трогаем (становится no-op, уйдёт при TS-порте). Выбор версии PlantUML в `new` сохраняется — он управляет выбором JAR.
- Существующих проектов пользователей изменение не касается — только новые `c4builder new`.

## Capabilities

### New Capabilities
- `project-template`: требования к демо-проекту, генерируемому `c4builder new` — офлайн-сборка, stdlib-инклюды, пример `.iuml`, кириллица.

### Modified Capabilities

_нет — существующих спеков ещё нет._

## Impact

- Данные: `template/src/**/*.puml` (6 файлов), новые файлы `.iuml` и кириллической страницы, `vendor/C4-PlantUML/C4.code-snippets`.
- Продуктовый JS-код не меняется.
- Внешний вид демо-диаграмм может немного измениться (версия C4 из stdlib JAR vs версия с URL) — приемлемо.
- Последовательность: этот change выполняется **до** `golden-test-ci` (шаблон — его fixture).

## design

[Обзор](#C4-Builder)

# Design: template-offline

## Context

Шаблон `template/src` копируется пользователю при `c4builder new` с подстановкой `{{plantumlVersion}}` в URL-инклюды C4-PlantUML. Рендер идёт локальным вендорным JAR (PlantUML ≥1.2020 несёт C4-PlantUML в stdlib). Шаблон станет fixture golden-теста, поэтому обязан собираться офлайн.

## Goals / Non-Goals

**Goals:**
- Демо-проект собирается полностью офлайн сразу после `c4builder new`.
- Демо показывает паттерны реального использования: stdlib-инклюды, общий `.iuml`, кириллица.

**Non-Goals:**
- Неинтерактивный режим `c4builder new` (отдельный будущий change).
- Правки продуктового JS-кода (`cli.new.js` остаётся как есть).
- Перевод всего демо на русский — кириллица точечно, демо остаётся Internet Banking System.

## Decisions

1. **stdlib-инклюды (`!include <C4/C4_Container>`), а не локальный вендоринг C4-PlantUML в шаблон.** C4 уже вшит в PlantUML JAR — ноль дополнительных файлов у пользователя, офлайн гарантирован. Alternative — класть копию C4-PlantUML в каждый новый проект: больше контроля версии, но мусор в каждом проекте и рассинхрон с JAR; отвергнуто.
2. **Код подстановки `{{plantumlVersion}}` в `cli.new.js` не трогаем** — после удаления плейсхолдеров из puml он становится безвредным no-op. Удаление кода — забота TS-порта; здесь change остаётся data-only и тривиально ревьюится.
3. **`.iuml`-пример** — один общий `styles.iuml` в корне `src` (тема/цвета), подключается из двух диаграмм через относительный `!include` — ровно паттерн arch, который должен покрыть golden.
4. **Кириллица** — одна новая страница (md с русским текстом + маленькая C4-диаграмма с русскими подписями элементов), не перевод существующих. Демонстрирует рабочую кириллицу и попадает в golden-контракт.
5. **Сниппеты** (`C4.code-snippets`) переводятся на те же stdlib-инклюды — единый стиль с шаблоном.

## Risks / Trade-offs

- [Вид демо-диаграмм слегка изменится: версия C4 в stdlib JAR ≠ версия, тянувшаяся по URL] → приемлемо для демо; фиксируется глазами при ревью SVG.
- [ditaa-диаграмма шаблона может требовать особого обращения при рендере] → проверить сборку всего шаблона локально в рамках задач; при проблемах — заменить ditaa на обычную диаграмму (демо-ценность у неё низкая).
- [Пользователи, привыкшие к URL-инклюдам из старого демо] → существующие проекты не трогаем; README шаблона упоминает stdlib.

## tasks

[Обзор](#C4-Builder)

# Tasks: template-offline

## 1. Инклюды

- [x] 1.1 Заменить URL-инклюды на stdlib `!include <C4/...>` в 6 файлах `template/src/**/*.puml` (context, system, 2×container, dynamic, deployment)
- [x] 1.2 Перевести `vendor/C4-PlantUML/C4.code-snippets` (5 вхождений) на stdlib-инклюды

## 2. Новый контент демо

- [x] 2.1 Добавить общий `template/src/styles.iuml` (тема/цвета) и подключить его относительным `!include` из двух существующих диаграмм
- [x] 2.2 Добавить страницу с кириллицей: md с русским текстом + C4-диаграмма с русскими подписями элементов
- [x] 2.3 Упомянуть stdlib-инклюды и `.iuml`-паттерн в `template/readme.md`

## 3. Проверка

- [x] 3.1 Создать проект из шаблона (вручную скопировать `template/src` + конфиг), собрать локальным JAR без сети, глазами проверить SVG (stdlib, .iuml-стили, кириллица, ditaa)
- [x] 3.2 Убедиться `grep -r "include http" template/ vendor/C4-PlantUML/` пуст; при проблеме с ditaa — заменить диаграмму и зафиксировать в design

## specs

[Обзор](#C4-Builder)

- [project-template](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-template-offline/specs/project-template/project-template)

## project-template

[Обзор](#C4-Builder)

# project-template

## ADDED Requirements

### Requirement: Демо-проект собирается офлайн
Проект, созданный `c4builder new`, SHALL собираться без доступа в интернет: рендер всех диаграмм шаблона MUST выполняться локальным PlantUML JAR без сетевых обращений.

#### Scenario: Сборка нового проекта без сети
- **WHEN** проект создан из шаблона и `c4builder` запущен в окружении без доступа в интернет
- **THEN** сборка завершается успешно и все диаграммы шаблона отрендерены

### Requirement: Диаграммы шаблона используют stdlib-инклюды
Все `.puml` шаблона MUST подключать C4-PlantUML через stdlib (`!include <C4/...>`); http(s)-инклюды в шаблоне и в VS Code-сниппетах (`C4.code-snippets`) MUST отсутствовать.

#### Scenario: Проверка инклюдов шаблона
- **WHEN** просматриваются `.puml` шаблона и файл сниппетов
- **THEN** ни один не содержит `!include http`, а C4-диаграммы используют `!include <C4/...>`

### Requirement: Шаблон демонстрирует локальный .iuml
Шаблон MUST содержать общий `.iuml`-файл (стили/тема), подключаемый минимум из двух диаграмм относительным `!include`.

#### Scenario: Сборка диаграмм с .iuml-инклюдом
- **WHEN** собирается новый проект из шаблона
- **THEN** диаграммы, подключающие общий `.iuml`, рендерятся успешно с применёнными стилями

### Requirement: Шаблон демонстрирует кириллицу
Шаблон MUST содержать страницу с русским md-текстом и диаграмму с кириллическими подписями элементов.

#### Scenario: Кириллица в собранном выходе
- **WHEN** собирается новый проект из шаблона
- **THEN** кириллический текст присутствует без искажений в выходных md и в SVG кириллической диаграммы

## 2026-07-04-plantuml-java-direct

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-04 · **Tasks:** <progress value="15" max="15"></progress> 15/15 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/tasks/tasks) · [README](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/README/README) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/specs/specs)

# Прямой вызов java + Smetana (отказ от внешнего graphviz)

## Why

Рендер диаграмм сейчас идёт через `node-plantuml` (0.9.0, заброшен с 2018, тянет
nailgun-хвосты) и требует **внешнего graphviz/dot**. Это две связанные боли:

- **Хрупкая зависимость окружения.** graphviz ставится отдельно (CI: `apt-get`,
  разработчик: вручную), а версия dot напрямую влияет на layout SVG. Golden-тест
  из-за этого пришлось объявить «CI — источник истины»: локальный `npm test` на
  машине с другим graphviz падает по layout.
- **Тупик для развития.** `node-plantuml` не пробрасывает произвольные флаги JAR —
  ни `-Playout`, ни `-S`, ни pragma. Любая настройка рендера упирается в форк
  заброшенного пакета.

PlantUML 1.2025.2 (уже в `vendor/`) умеет раскладывать граф на чистой Java —
движок **Smetana**, активируется `-Playout=smetana`. Спайки подтвердили: dot
перестаёт вызываться, все диаграммы демо-шаблона и 42 диаграммы C4-модели репо
`arch` рендерятся без ошибок. Убрав graphviz, заодно убираем и `node-plantuml`:
проще вызвать `java` напрямую и получить полный контроль над флагами.

## What Changes

- **Рендер вызывает `java` напрямую** (`child_process.spawn`) из `build.js`, минуя
  `node-plantuml`; argv включает `-Playout=smetana`. Вывод по-прежнему берётся из
  stdout (`-pipe`), не через `-o`, — чтобы имена файлов не зависели от
  `@startuml <name>` (PlantUML именует выход по имени диаграммы, а c4builder кладёт
  результат по имени `.puml`-файла).
- **Внешний graphviz больше не нужен.** Из `ci.yml` удаляется шаг установки
  graphviz; README/доки: требуется только Java (JRE), graphviz — нет.
- **`node-plantuml` удаляется** из `dependencies` (вместе с nailgun-транзитивом).
- **Детерминизм текста через vendored-шрифт.** `textLength` в SVG считается из
  AWT-метрик шрифта; дефолтный `sans-serif` резолвится по-разному на разных
  системах. В `vendor/fonts/` кладётся Liberation Sans, отдаётся JVM и включается
  `-SdefaultFontName`, чтобы метрики не зависели от машины. Голого имени шрифта
  недостаточно — при отсутствии на машине PlantUML молча уходит в fallback.
- **Golden-эталон пересоздаётся** под Smetana-layout (дифф в PR = визуальный аудит
  перелёта всех диаграмм). После пина шрифта эталон становится воспроизводимым на
  любой машине — костыль «CI — источник истины» снимается.
- **ditaa** (`@startditaa` → png) рендерится тем же прямым вызовом; Smetana его не
  затрагивает — проверяется, что вывод не изменился.

## Capabilities

### New Capabilities
- `diagram-rendering`: рендер диаграмм оффлайн, без внешнего graphviz — layout на
  Smetana, прямой вызов java, детерминированные метрики текста через vendored-шрифт.

### Modified Capabilities
- `ci-validation`: workflow больше не устанавливает graphviz.
- `regression-testing`: golden-эталон воспроизводим независимо от машины (не только
  на пинованном CI-раннере).

## Impact

- `build.js` (`generateImages` и вспомогательные): вызов рендера переписывается.
- `package.json`: удаляется `node-plantuml`; появляется каталог `vendor/fonts/`.
- `.github/workflows/ci.yml`: убирается установка graphviz.
- `test/golden/`: эталон регенерируется под Smetana.
- Требования: java остаётся обязательной; graphviz — исключается.
- Поведение CLI и набор выходных файлов не меняются (меняется только layout SVG).

## design

[Обзор](#C4-Builder)

# Design: plantuml-java-direct

## Context

c4builder рендерит `.puml` в SVG/PNG через `node-plantuml.generate(file, {...})`,
который спавнит `java -jar <vendor JAR>` с жёстко ограниченным argv. JAR подменяется
на вендорный через `PLANTUML_HOME`. Layout считает **внешний graphviz/dot** →
результат зависит от версии dot на машине. Главный потребитель — репо `arch`
(C4-PlantUML stdlib, локальные `.iuml`, кириллица, `diagramFormat=svg`).

Место в цепочке модернизации: после `template-offline` и `golden-test-ci`
(страховочная сеть уже стоит), реализует пункт плана «java напрямую + Smetana».

## Спайки (проведены в explore, легли в основу решений)

1. **Активация Smetana.** `-Playout=smetana` = глобальный `!pragma layout smetana`
   из CLI, без правки пользовательских `.puml`.
2. **graphviz реально уходит.** Рендер с заведомо битым `dot` (`/nonexistent/dot`):
   без Smetana — `IOException: Cannot run program`; со Smetana — SVG отрендерился,
   dot не вызывался. Все 7 типов диаграмм шаблона — OK, кириллица цела.
3. **Аудит `arch`.** 42 реальных C4-диаграммы (`src/c4`, один JVM, Smetana):
   0 ошибок рендера, 0 `UNSURE`, 0 exceptions, viewBox в норме (max 2003×1008).
4. **Шрифт → детерминизм.** Отпечаток геометрии (`textLength`/`width`/`height`)
   context.puml:
   - дефолт `sans-serif` (Arch) ≠ `Liberation Sans` ≠ `FreeSans` — шрифт меняет числа;
   - `Liberation Sans` два прогона подряд — идентичны (детерминизм при фиксации);
   - `DejaVu Sans` (нет на Arch) == дефолт → **PlantUML молча уходит в fallback**.
     Вывод: одного `-SdefaultFontName` мало, шрифт должен физически присутствовать.

## Goals / Non-Goals

**Goals:**
- Убрать внешний graphviz из зависимостей рантайма и CI.
- Убрать заброшенный `node-plantuml`, вызывать `java` напрямую.
- Сделать golden-эталон воспроизводимым на любой машине (пин шрифта).

**Non-Goals:**
- Смена формата/структуры выходов, поведения CLI.
- Порт на TypeScript (отдельный change).
- Замена PlantUML на D2/иной движок (отдельный change).
- Удаление старых вендорных JAR (`vendor-cleanup` — отдельно).
- Поддержка онлайн-рендера (`plantumlServerUrl`) — вне scope, не трогаем.

## Decisions

1. **Прямой `spawn('java', argv)` в `build.js`.** Базовый argv:
   ```
   -Djava.awt.headless=true
   -Dplantuml.include.path=<cwd>
   -Dsun.java2d.fontpath=prepend:<repo>/vendor/fonts   # vendored-шрифт
   -jar <repo>/vendor/plantuml-1.2025.2.jar
   -Playout=smetana
   -SdefaultFontName=Liberation Sans
   -charset UTF-8
   -t{svg|png}                                         # png для ditaa
   -pipe                                               # источник — stdin/stdout
   ```
   `.puml` подаётся в stdin, SVG читается из stdout и пишется в целевой путь —
   как сейчас делает `node-plantuml`.

2. **Сохраняем `-pipe`, не `-o`.** PlantUML с `-o` именует файл по `@startuml <name>`
   (в `arch` видели `Selling Agent Sequence.svg`), а c4builder кладёт результат по
   имени `.puml`-файла. `-pipe` разрывает эту связь: имя выхода задаёт c4builder.
   Include (`!include ../styles.iuml`) при `-pipe` резолвится от `-Dplantuml.include.path`
   и `-Dplantuml.include.path`-каталога — проверяется, что стилевые/`.iuml`-инклюды и
   stdlib `<C4/...>` резолвятся так же, как раньше (это ключевой риск pipe-режима).

3. **Vendored Liberation Sans.** Кладём `LiberationSans-{Regular,Bold,Italic,BoldItalic}.ttf`
   в `vendor/fonts/`, отдаём JVM через `-Dsun.java2d.fontpath=prepend:` и включаем
   `-SdefaultFontName=Liberation Sans`. Liberation Sans — метрически-совместим с Arial,
   лицензия OFL (можно вендорить), присутствует и на Ubuntu-раннере. Alternative —
   `skinparam` без vendoring: отвергнут (спайк показал молчаливый fallback при
   отсутствии шрифта). Спайк в tasks: подтвердить, что vendored TTF реально
   подхватывается (метрики == системной установке).

4. **Golden — регенерация в этом же change.** Дифф `test/golden/` в PR = аудит того,
   как Smetana переложила каждую диаграмму. После пина шрифта эталон воспроизводим
   локально и на CI одинаково → в `regression-testing` фиксируем инвариант
   «эталон не зависит от машины», а костыль «CI — источник истины» из `test/README.md`
   ослабляется до «при смене JDK-мажора возможна регенерация».

5. **`node-plantuml` вон.** Удаляется из `dependencies`; исчезает и `PLANTUML_HOME`-хак.
   Выбор вендорного JAR по `PLANTUML_VERSION` остаётся (маппинг version→jar в utils).

## Risks / Trade-offs

- **[pipe-режим и резолвинг include]** — главный риск: `<C4/...>` (stdlib из JAR),
  `!include styles.iuml`/`../styles.iuml` (локальные) должны резолвиться идентично.
  Проверяется golden-диффом по шаблону (в нём есть оба вида) до регенерации.
- **[Детерминизм между JDK]** — advance-widths берутся из TTF (`hmtx`) и оказались
  стабильны: метрики/layout совпали и между мажорами OpenJDK 17/21, и между
  дистрибутивами (локальный OpenJDK vs Temurin на CI) — все C4-диаграммы байт-в-байт.
  Остаточное расхождение только между **дистрибутивами** JDK — тесселяция глифов
  (буквенные иконки class-диаграммы: кубические vs квадратичные Безье, метрики те же).
  Поэтому канон эталона — CI (Temurin 21); закрывается регенерацией из CI-артефакта.
- **[Качество Smetana vs graphviz]** — на плотных графах Smetana исторически слабее
  (перекрытия рёбер). Аудит `arch` (42 диаграммы) расхождений не выявил; будущие
  тяжёлые диаграммы отлавливаются golden-диффом.
- **[`UNSURE_ABOUT` в stderr]** — Smetana печатает диагностику на некоторых
  диаграммах (воспроизвелось на class-диаграмме шаблона, не на `arch`). SVG корректен;
  нужно не выводить этот шум пользователю (фильтрация stderr рендера).
- **[ditaa]** — спайк показал: `-Playout=smetana` на `@startditaa` **не** безвреден —
  меняет размер холста PNG (390×154 → 510×182). Решение: для ditaa флаг не передаётся;
  тогда PNG-выход байт-в-байт совпадает с историческим (вендорный шрифт на ditaa не
  влияет — у него собственный движок текста).

## Open Questions

- ~~Ослаблять ли `test/README.md` полностью?~~ Решено по итогу CI: layout/метрики
  воспроизводимы cross-machine, но тесселяция глифов различается между дистрибутивами
  JDK → раздел «CI — источник истины» ослаблен до «канон = CI (Temurin 21), процедура
  регенерации на случай другого дистрибутива JDK».

## tasks

[Обзор](#C4-Builder)

# Tasks: plantuml-java-direct

## 1. Спайки (снять остаточную неопределённость до правки кода)

- [x] 1.1 Подтвердить, что vendored TTF (`vendor/fonts/LiberationSans*`) подхватывается
      через `-Dsun.java2d.fontpath=prepend:` и даёт те же метрики, что системный
      Liberation Sans (сравнить отпечаток геометрии)
      → шрифт применяется (геометрия ≠ дефолтного sans-serif), два прогона байт-идентичны
- [x] 1.2 Проверить резолвинг инклюдов в `-pipe`-режиме: stdlib `<C4/...>`, локальный
      `!include styles.iuml` и `!include ../styles.iuml` из вложенной папки — на копии
      `template/src`, до правки продуктового кода
      → все три вида резолвятся; кириллица цела; сломанный `GRAPHVIZ_DOT` не мешает (dot не зовётся)
- [x] 1.3 Спайк детерминизма между мажорами JDK: метрики Liberation Sans на двух
      JDK-мажорах — решить, ослаблять ли `test/README.md` полностью
      → JDK 17 и 21 дают байт-идентичный SVG → эталон воспроизводим между мажорами;
        `test/README.md` ослаблен до «регенерация только при смене JDK-мажора»

## 2. Вендорный шрифт

- [x] 2.1 Добавить `vendor/fonts/LiberationSans-{Regular,Bold,Italic,BoldItalic}.ttf`
      (OFL) в git; зафиксировать лицензию/происхождение (`vendor/fonts/README.md`)
- [x] 2.2 Убедиться, что `.npmignore`/пакет включает `vendor/fonts/`
      → `npm pack --dry-run` подтверждает: 4 TTF + README попадают в пакет

## 3. Прямой вызов java + Smetana

- [x] 3.1 Реализовать в `build.js` прямой `spawn('java', argv)`: headless,
      `-Dplantuml.include.path`, `-Dsun.java2d.fontpath=prepend:vendor/fonts`,
      `-jar <vendor jar>`, `-Playout=smetana`, `-SdefaultFontName=Liberation Sans`,
      `-charset`, `-t{svg|png}`, `-pipe`; stdout → целевой файл
- [x] 3.2 Сохранить выбор JAR по `PLANTUML_VERSION` (маппинг version→jar); убрать
      `PLANTUML_HOME`-хак
- [x] 3.3 Отфильтровать диагностический шум Smetana (`UNSURE_ABOUT…`) из stderr, не
      показывать пользователю; реальные ошибки рендера пробрасывать
- [x] 3.4 ditaa (`@startditaa` → png): рендерить тем же путём, проверить, что PNG-выход
      не изменился
      → находка: `-Playout=smetana` меняет ditaa-холст (390×154→510×182), для ditaa флаг
        не передаётся → PNG байт-в-байт совпадает с историческим (шрифт на ditaa не влияет)
- [x] 3.5 Удалить `node-plantuml` из `dependencies`, прогнать `npm install`, убедиться,
      что nailgun-транзитив ушёл (ушли и `node-nailgun-*`, `plantuml-encoder`)

## 4. CI и документация

- [x] 4.1 Убрать из `.github/workflows/ci.yml` шаг установки graphviz
- [x] 4.2 README/доки: java обязательна, graphviz не требуется; обновить `test/README.md`
      согласно итогу спайка 1.3
      → правки: `README.MD`, `docs/README.MD`, `cli.new.js` (сообщение),
        `Dockerfile` (убран graphviz + node-plantuml-хак), `test/README.md`

## 5. Golden-эталон

- [x] 5.1 Пересоздать `test/golden/` под Smetana+шрифт (`npm run test:golden:update`),
      дифф в PR — визуальный аудит перелёта диаграмм
- [x] 5.2 Прогнать CI (Node 22/24) без graphviz: тесты зелёные, эталон совпадает
      → первый прогон выявил cross-vendor различие тесселяции глифов в class.svg
        (C4-диаграммы совпали байт-в-байт); эталон канонично пересоздан из CI-артефакта
        (Temurin 21), повторный прогон подтверждает зелёный
- [x] 5.3 Проверить локально `npm test` на совпадающем JDK-мажоре: совпадает с CI
      (инвариант «эталон не зависит от машины») — JDK 21 локально == Temurin 21 на CI (мажор)

## README

[Обзор](#C4-Builder)

# plantuml-java-direct

Прямой вызов java со Smetana вместо node-plantuml: отказ от внешнего graphviz, детерминированный рендер через vendored-шрифт

## specs

[Обзор](#C4-Builder)

- [ci-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/specs/ci-validation/ci-validation)
- [diagram-rendering](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/specs/diagram-rendering/diagram-rendering)
- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-plantuml-java-direct/specs/regression-testing/regression-testing)

## ci-validation

[Обзор](#C4-Builder)

# ci-validation

## MODIFIED Requirements

### Requirement: Тесты выполняются на каждый PR и push в master
Репозиторий SHALL содержать GitHub Actions workflow (`.github/workflows/ci.yml`),
запускающий полный тестовый набор на события `pull_request` и `push` в `master`.
Workflow MUST выполнять тесты на матрице Node.js 22 и 24, с установленной Java
(Temurin), на пинованном образе раннера (`ubuntu-24.04`). Workflow MUST NOT
устанавливать внешний graphviz — рендер диаграмм выполняется Java-движком Smetana.

#### Scenario: Открыт pull request
- **WHEN** открыт или обновлён PR
- **THEN** workflow устанавливает зависимости (`npm ci`) и запускает тесты на Node 22 и Node 24

#### Scenario: Push в master
- **WHEN** выполнен push в ветку master
- **THEN** workflow запускает тот же тестовый набор

#### Scenario: graphviz не устанавливается
- **WHEN** выполняется job workflow
- **THEN** среди шагов нет установки graphviz, а тесты рендера при этом проходят

## diagram-rendering

[Обзор](#C4-Builder)

# diagram-rendering

## ADDED Requirements

### Requirement: Диаграммы рендерятся без внешнего graphviz
Сборка SHALL рендерить PlantUML-диаграммы с использованием встроенного в PlantUML
Java-движка раскладки (Smetana, `-Playout=smetana`) и MUST NOT требовать наличия
внешнего graphviz/dot. Отсутствие или неработоспособность `dot` в системе MUST NOT
приводить к ошибке рендера.

#### Scenario: Рендер при отсутствующем graphviz
- **WHEN** выполняется сборка, а исполняемый файл `dot` в системе недоступен
- **THEN** все диаграммы (C4 context/container/component/deployment/dynamic, class,
  sequence) успешно рендерятся в SVG, а кириллица в выходе сохраняется

#### Scenario: dot не вызывается
- **WHEN** запущен рендер диаграмм
- **THEN** процесс сборки не порождает вызовов внешнего `dot`

### Requirement: Рендер вызывает java напрямую
Сборка SHALL запускать PlantUML прямым вызовом `java` с вендорным JAR, без
посреднической библиотеки `node-plantuml`. Источником данных MUST быть stdin/stdout
(pipe-режим), чтобы имя выходного файла определялось c4builder по имени `.puml`-файла,
а не по имени диаграммы из директивы `@startuml`.

#### Scenario: Имя выходного файла независимо от @startuml
- **WHEN** рендерится диаграмма, у которой в `@startuml <name>` задано имя, отличное
  от имени файла
- **THEN** выходной файл именуется по имени `.puml`-файла (как прежде), а не по `<name>`

#### Scenario: Локальные и stdlib-инклюды резолвятся
- **WHEN** рендерится диаграмма с `!include <C4/...>` (stdlib) и `!include ../styles.iuml`
  (локальный файл)
- **THEN** оба вида инклюдов резолвятся, диаграмма собирается корректно

### Requirement: Детерминированные метрики текста через вендорный шрифт
Ширина текста в SVG зависит от метрик шрифта, поэтому сборка SHALL использовать
шрифт, поставляемый в составе репозитория (`vendor/fonts/`), и задавать его как
шрифт диаграмм по умолчанию. Шрифт MUST физически предоставляться JVM (а не только
задаваться по имени), чтобы исключить молчаливый откат на системный шрифт.

#### Scenario: Рендер использует вендорный шрифт
- **WHEN** выполняется сборка на машине, где заданный шрифт не установлен системно
- **THEN** рендер использует шрифт из `vendor/fonts/`, а не системный fallback

#### Scenario: Повторяемость метрик
- **WHEN** одна и та же диаграмма рендерится дважды на одной машине
- **THEN** геометрия выходного SVG (координаты и `textLength`) байт-в-байт идентична

## regression-testing

[Обзор](#C4-Builder)

# regression-testing

## ADDED Requirements

### Requirement: Golden-эталон воспроизводим независимо от машины
Golden-эталон SHALL быть детерминированным и не зависеть от версии внешнего graphviz —
за счёт Java-движка раскладки (Smetana) и вендорного шрифта. Регенерация эталона на
разных машинах с одинаковой мажорной версией JDK MUST давать идентичное дерево
выходов; необходимость калибровать эталон исключительно по CI-раннеру устраняется.

#### Scenario: Регенерация на разных машинах
- **WHEN** эталон регенерируется на двух машинах с одинаковой мажорной версией JDK
  и одним вендорным JAR/шрифтом
- **THEN** нормализованное дерево выходов идентично

#### Scenario: Локальный прогон совпадает с CI
- **WHEN** разработчик запускает `npm test` локально при совпадающей мажорной версии JDK
- **THEN** golden-тест проходит без расхождений с эталоном, снятым на CI

## 2026-07-04-golden-test-ci

[Обзор](#C4-Builder)

**Schema:** spec-driven · **Created:** 2026-07-04 · **Tasks:** <progress value="11" max="11"></progress> 11/11 (100%) · **Updated:** 2026-10-06

[design](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/design/design) · [tasks](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/tasks/tasks) · [specs](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/specs/specs)

# Golden-тест и CI-проверки

## Why

В проекте ноль тестов, а CI только публикует пакет — регресс заметить нечем. Впереди цепочка крупных изменений (удаление PDF, порт на TypeScript, замена PlantUML-рендера, resvg, D2): без страховочной сети каждое из них непроверяемо. Golden-тест фиксирует текущее поведение как контракт **до** любых переделок — прежде всего совместимость с главным потребителем, репо `arch` (108 .puml, C4-PlantUML stdlib, локальные .iuml-инклюды, кириллица, diagramFormat=svg).

## What Changes

- Fixture — сам демо-шаблон `template/src` (после change'а `template-offline` он содержит stdlib-инклюды, локальный `.iuml`, кириллицу и собирается офлайн). Отдельный рукотворный fixture не заводится; тест-хелпер копирует шаблон во временную директорию и кладёт готовый `.c4builder` (`diagramFormat=svg`, `generateLocalImages=true`) — неинтерактивный эквивалент `c4builder new`.
- Golden e2e-тест: прогон текущего CLI по fixture, сравнение полного дерева выходных файлов с закоммиченным эталоном (после нормализации недетерминизма: комментарии PlantUML-версии в SVG и т.п.).
- Тест-раннер vitest (работает с текущим CommonJS, останется после порта на TS); npm-скрипты `test` / `test:golden`.
- Новый workflow `.github/workflows/ci.yml`: прогон тестов на PR и push, матрица Node 22/24, setup-java (Temurin) для реального PlantUML-рендера.
- PDF-выходы golden-тестом сознательно **не** покрываются: PDF недетерминирован и удаляется следующим change'ом (`remove-pdf-output`).
- Путь `c4builder new` не покрывается: он насквозь интерактивен (inquirer без флагов); неинтерактивный режим и e2e «new → build» — будущий change (`new-noninteractive`).
- Продуктовый код не меняется (кроме случая, если golden вскроет недетерминизм, который надо будет стабилизировать).
- Предусловие: change `template-offline` применён (шаблон собирается офлайн).

## Capabilities

### New Capabilities
- `regression-testing`: golden-тест фиксирует выходы сборки (site/md/complete-md + SVG-диаграммы) на эталонном fixture-проекте и падает при любом расхождении.
- `ci-validation`: GitHub Actions прогоняет тесты на каждый PR и push в master; публикация возможна только при зелёных проверках.

### Modified Capabilities

_нет — существующих спеков ещё нет._

## Impact

- Новые каталоги: `test/` (тесты и эталонные выходы; fixture — существующий `template/src`).
- Новые dev-зависимости: `vitest`.
- `package.json`: секция `scripts` (сейчас пустая).
- Новый `.github/workflows/ci.yml`; существующие `publish.yml` / `docker-publish.yml` не трогаем (связка «публикация после зелёного CI» — отдельным шагом, чтобы не блокировать релизы до стабилизации тестов).
- Поведение CLI не меняется.

## design

[Обзор](#C4-Builder)

# Design: golden-test-ci

## Context

c4builder — CLI на CommonJS (~2300 строк), тестов нет, CI только публикует. Конфиг проекта читается из файла `.c4builder` в cwd (Configstore с явным `configPath`), кэш чексумм диаграмм — из `.c4builder.cache`; при наличии конфига CLI работает неинтерактивно. PlantUML рендерится через node-plantuml, JAR подменяется на вендорный через `PLANTUML_HOME` (выбор — опцией `PLANTUML_VERSION`). Главный потребитель — репо `arch`: C4-PlantUML stdlib, локальные `.iuml`, кириллица, `diagramFormat=svg`, `generateLocalImages=true`.

Место в цепочке: сразу после `template-offline` (шаблон переведён на stdlib-инклюды, содержит `.iuml` и кириллицу, собирается офлайн — и используется здесь как fixture), до remove-pdf → ts-migration → рендер-фич. Задача — построить страховочную сеть до любых переделок кода.

## Goals / Non-Goals

**Goals:**
- Зафиксировать текущее поведение сборки (site / md / complete-md + SVG) как исполняемый контракт.
- Тесты запускаются одной командой локально и на каждый PR в GitHub Actions.
- Fixture воспроизводит ключевые особенности `arch` (через демо-шаблон: stdlib, `.iuml`, кириллица).

**Non-Goals:**
- Юнит-тесты отдельных функций (придут вместе с TS-портом).
- Покрытие PDF-выходов (PDF удаляется следующим change'ом).
- Покрытие интерактивного режима (inquirer), пути `c4builder new` (интерактивен насквозь; неинтерактивные флаги — будущий change `new-noninteractive`) и `c4builder site` (dev-сервер).
- Привязка publish-workflow к зелёному CI (отдельный шаг после стабилизации).
- Изменение продуктового кода.

## Decisions

1. **Тест-раннер — vitest** (не `node:test`): встроенные снапшоты и диффы, watch-режим, нативная поддержка будущего TS без перенастройки. Alternative: `node:test` без зависимостей — отвергнут из-за слабой эргономики диффов больших деревьев.

2. **E2E через реальный запуск CLI**, не программный вызов `build()`: тест копирует fixture во временную директорию, кладёт готовый `.c4builder` и спавнит `node <repo>/index.js` с `cwd=tmp`. Так покрываются `cli.js`, `getOptions`, миграция кэша — весь неинтерактивный путь целиком. Программный вызов оставляем юнит-тестам будущего.

3. **Fixture — демо-шаблон `template/src`**, отдельный «мини-arch» не заводим. Тест-хелпер копирует шаблон в tmp и кладёт готовый `.c4builder` (`diagramFormat=svg`, `generateLocalImages=true`, `PLANTUML_VERSION` пинован на вендорный 1.2025.2, выходы site/md/complete-md, PDF выключен) — неинтерактивный эквивалент `c4builder new`. После `template-offline` шаблон покрывает stdlib-инклюды, `.iuml` и кириллицу, рендер офлайн и детерминирован по версии PlantUML. Правка шаблона в будущем = осознанная регенерация эталона в том же PR: дифф эталона наглядно показывает эффект правки. Alternative — замороженная копия шаблона в `test/fixtures/`: развязывает демо и тесты, но дублирует контент и позволяет шаблону незаметно сломаться; отвергнут.

4. **Golden-хранение и сравнение**: эталонное дерево выходов коммитится в `test/golden/`. Сравнение — (а) идентичность списка файлов, (б) байтовое равенство содержимого после нормализации: из SVG вырезаются XML-комментарии (метаданные/версия PlantUML), все файлы приводятся к LF. Обновление эталона только явно: `UPDATE_GOLDEN=1 npm run test:golden` (скрипт `test:golden:update`).

5. **Кэш-инвариант вторым тест-кейсом**: повторная сборка в той же tmp-директории (с уже наполненным `.c4builder.cache`) обязана дать выход, идентичный первому прогону, — фиксируем корректность checksum-кэша.

6. **CI**: workflow `ci.yml` на `pull_request` + `push` в master; runner пинован `ubuntu-24.04` (стабильная версия graphviz); матрица Node 22/24; `actions/setup-java` (Temurin 21) + `apt-get install graphviz`; `npm ci --ignore-scripts`, `npm test`; `concurrency` с cancel-in-progress.

## Risks / Trade-offs

- [Расхождение layout из-за версии graphviz локально vs CI] → CI объявляется источником истины для эталона; runner пинован; при локальном расхождении — регенерация эталона артефактом из CI или запуск в docker-образе проекта. Риск исчезает после перехода на Smetana (change `plantuml-java-direct`).
- [Недетерминизм внутри SVG (метаданные, порядок атрибутов)] → нормализация комментариев; если вскроется большее — расширяем нормализатор, это часть данного change.
- [JVM-старт и рендер удлиняют CI] → fixture маленький (3–4 диаграммы), ожидаемо < 1 мин на job.
- [Тест зависит от вендорного JAR в репо] → JAR уже в git (vendor/), удаление старых JAR — забота будущего change'а `vendor-cleanup`, здесь пин на существующий.
- [Связность template ↔ golden: правка демо ломает эталон] → это осознанно: несовпадение при неумышленной правке — ровно то, что тест должен ловить; умышленная правка сопровождается `UPDATE_GOLDEN=1` в том же PR.

## Open Questions

- нет блокирующих; вопрос «привязать publish к зелёному CI» сознательно вынесен за рамки.

## tasks

[Обзор](#C4-Builder)

# Tasks: golden-test-ci

## 1. Инфраструктура тестов

- [x] 1.1 Добавить vitest в devDependencies, завести `vitest.config` и npm-скрипты `test`, `test:golden`, `test:golden:update` в package.json
- [x] 1.2 Обновить `.gitignore`/`.npmignore`: временные выходы тестов не попадают в git и в пакет, `test/golden/` — попадает в git

## 2. Fixture из шаблона

- [x] 2.1 Убедиться, что `template-offline` применён: `template/src` собирается офлайн (нет URL-инклюдов), содержит `.iuml` и кириллицу
- [x] 2.2 Подготовить эталонный конфиг `.c4builder` для тестов: `diagramFormat=svg`, `generateLocalImages=true`, `PLANTUML_VERSION` пинован на вендорный 1.2025.2, включены выходы site/md/complete-md, PDF выключен

## 3. Golden-тест

- [x] 3.1 Реализовать хелперы: копирование `template/src` в tmp + подкладывание `.c4builder` (неинтерактивный эквивалент `new`), запуск `node index.js` с `cwd=tmp`, рекурсивный сбор дерева файлов, нормализация (SVG-комментарии, LF)
- [x] 3.2 Реализовать сравнение с эталоном (список файлов + нормализованное содержимое, внятный дифф) и режим `UPDATE_GOLDEN=1`
- [x] 3.3 Тест-кейс: сборка fixture совпадает с эталоном; проверка наличия SVG для stdlib- и .iuml-диаграмм и сохранности кириллицы
- [x] 3.4 Тест-кейс: повторная сборка с тёплым кэшем (`.c4builder.cache`) идентична первой
- [x] 3.5 Сгенерировать и закоммитить эталон `test/golden/`, убедиться в детерминизме двух подряд чистых прогонов

## 4. GitHub Actions

- [x] 4.1 Создать `.github/workflows/ci.yml`: `pull_request` + `push` в master, runner `ubuntu-24.04`, матрица Node 22/24, setup-java Temurin 21, установка graphviz, `npm ci --ignore-scripts`, `npm test`, concurrency с cancel-in-progress
- [x] 4.2 Прогнать workflow на ветке (push/PR), при расхождении эталона из-за окружения CI — регенерировать эталон по артефакту CI и зафиксировать процедуру в test/README

## specs

[Обзор](#C4-Builder)

- [ci-validation](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/specs/ci-validation/ci-validation)
- [regression-testing](%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%20%D1%80%D0%B5%D1%88%D0%B5%D0%BD%D0%B8%D0%B9/Archive/2026-07-04-golden-test-ci/specs/regression-testing/regression-testing)

## ci-validation

[Обзор](#C4-Builder)

# ci-validation

## ADDED Requirements

### Requirement: Тесты выполняются на каждый PR и push в master
Репозиторий SHALL содержать GitHub Actions workflow (`.github/workflows/ci.yml`), запускающий полный тестовый набор на события `pull_request` и `push` в `master`. Workflow MUST выполнять тесты на матрице Node.js 22 и 24, с установленной Java (Temurin) и graphviz, на пинованном образе раннера (`ubuntu-24.04`).

#### Scenario: Открыт pull request
- **WHEN** открыт или обновлён PR
- **THEN** workflow устанавливает зависимости (`npm ci`) и запускает тесты на Node 22 и Node 24

#### Scenario: Push в master
- **WHEN** выполнен push в ветку master
- **THEN** workflow запускает тот же тестовый набор

### Requirement: Падение тестов даёт красный статус проверки
Неуспешное завершение любого теста MUST приводить к неуспешному завершению workflow и красному статусу проверки на PR.

#### Scenario: Тест упал в PR
- **WHEN** хотя бы один тест завершился с ошибкой
- **THEN** job завершается с ненулевым кодом и PR получает failed-статус проверки

### Requirement: Конкурентные прогоны одной ветки отменяются
Workflow MUST использовать `concurrency` с отменой предыдущего незавершённого прогона той же ветки (cancel-in-progress), чтобы не копить очередь на быстрых итерациях.

#### Scenario: Повторный push в ту же ветку PR
- **WHEN** в ветку PR приходит новый push до завершения предыдущего прогона
- **THEN** предыдущий прогон отменяется и запускается новый

## regression-testing

[Обзор](#C4-Builder)

# regression-testing

## ADDED Requirements

### Requirement: Golden-сборка fixture соответствует эталону
Тестовый набор SHALL собирать fixture-проект «мини-arch» реальным запуском CLI (неинтерактивно, с готовым `.c4builder`) во временной директории и сравнивать полное дерево выходных файлов (site, md, complete-md, SVG-диаграммы) с закоммиченным эталоном. Сравнение MUST выполняться после нормализации (удаление XML-комментариев из SVG, приведение переводов строк к LF) и MUST включать идентичность списка файлов.

#### Scenario: Совпадение с эталоном
- **WHEN** golden-тест запускает сборку fixture и выход совпадает с эталоном после нормализации
- **THEN** тест проходит

#### Scenario: Расхождение с эталоном
- **WHEN** содержимое хотя бы одного выходного файла или сам список файлов отличается от эталона
- **THEN** тест падает с диффом, указывающим конкретные файлы и расхождения

### Requirement: Fixture — демо-шаблон проекта
Fixture'ом golden-теста SHALL служить существующий демо-шаблон `template/src` (после change'а `template-offline`: stdlib-инклюды, локальный `.iuml`, кириллица). Тест-хелпер MUST копировать шаблон во временную директорию и класть готовый `.c4builder` с `diagramFormat=svg`, `generateLocalImages=true`, пинованной версией PlantUML из vendor и включёнными выходами site/md/complete-md (без PDF).

#### Scenario: Сборка fixture из шаблона
- **WHEN** golden-тест собирает копию шаблона
- **THEN** в выходе присутствуют SVG для stdlib-диаграмм и для диаграмм с `.iuml`-инклюдом, а кириллица сохранена в выходных md и SVG

### Requirement: Повторная сборка с кэшем идентична первой
Повторный запуск сборки в той же рабочей директории (с наполненным `.c4builder.cache`) SHALL давать дерево выходных файлов, идентичное первому прогону.

#### Scenario: Второй прогон с тёплым кэшем
- **WHEN** сборка fixture выполняется второй раз без изменения исходников
- **THEN** выходное дерево байт-в-байт (после нормализации) совпадает с результатом первого прогона

### Requirement: Эталон обновляется только явной командой
Перезапись эталонного дерева MUST происходить только при явном запуске режима обновления (`UPDATE_GOLDEN=1` / npm-скрипт `test:golden:update`); обычный запуск тестов MUST NOT изменять эталон.

#### Scenario: Явное обновление эталона
- **WHEN** тесты запущены в режиме обновления эталона
- **THEN** эталонное дерево перезаписывается текущим нормализованным выходом сборки

#### Scenario: Обычный запуск не трогает эталон
- **WHEN** тесты запущены без режима обновления
- **THEN** файлы эталона остаются неизменными независимо от результата сравнения

## Included files

### src/styles.iuml

```plantuml
' Общая тема диаграмм сайта. Цвета — стандартные C4-PlantUML, как у лендинга;
' внешние системы темнее стандартного серого, чтобы белый текст читался.
' Подключается после stdlib-инклюда C4: !include styles.iuml (из корня src),
' !include ../styles.iuml (из папки страницы).

skinparam shadowing false
skinparam roundCorner 10

UpdateElementStyle("external_system", $bgColor="#5c6977", $borderColor="#46535f")
```