# C4-Builder

* [Overview](#Overview)
  * [01 Getting started](#01-Getting-started)
  * [02 Project](#02-Project)
  * [03 Diagrams](#03-Diagrams)
  * [04 Outputs](#04-Outputs)
  * [05 CLI and configuration](#05-CLI-and-configuration)
  * [06 Plugins](#06-Plugins)
  * [07 Docker and CI](#07-Docker-and-CI)
  * [08 Agents](#08-Agents)
  * [09 Development](#09-Development)
  * [Design log](#Design-log)
    * [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)

---

## Overview

# C4-Builder

**Architecture as code that an agent writes, checks and reads.**

C4-Builder is a CLI that builds a folder of markdown files and PlantUML, D2 or BPMN diagrams into
documentation: a docsify site, a markdown file per folder, or a single file. Folders define the
hierarchy of the [C4 model](https://c4model.com/) (system → container → component), and git
keeps the history of architecture decisions next to the code: a change to the architecture is
reviewed in a pull request like any other change.

This site is built by c4builder itself from the `docs/` folder of the repository; its diagrams
are rendered during the CI build.

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

LAYOUT_TOP_DOWN()

Person(dev, "Developer", "Writes markdown and diagrams, reviews architecture in pull requests")
Person(agent, "AI agent", "Claude Code, Codex, Cursor: edits the model and verifies it with c4builder check")

System(c4b, "C4-Builder", "CLI: builds a folder of markdown + PlantUML/D2 into documentation, checks individual diagrams")

System_Ext(engines, "Diagram engines", "PlantUML (bundled jar + Java, Smetana), D2 (WASM)")
System_Ext(openspec, "OpenSpec store", "Project specs and changes: proposal, design, tasks")
System_Ext(openapi, "OpenAPI contracts", "Service specs: a folder or a repository archive")
System_Ext(site, "Docsify site", "Static, no CDN: GitHub Pages, GitLab Pages, any web server")
System_Ext(md, "Markdown", "A README per folder or a single file for the repository")

Rel(dev, c4b, "Builds and previews", "c4builder --site -w")
Rel(agent, c4b, "Checks edits", "c4builder check")
Rel(c4b, engines, "Renders diagrams", "locally, offline")
Rel(c4b, openspec, "Publishes a section", "openspec plugin")
Rel(c4b, openapi, "Publishes swagger-ui", "openapi plugin")
Rel(c4b, site, "Builds")
Rel(c4b, md, "Builds")

SHOW_LEGEND()
@enduml
```

## How this fork differs from upstream

The original C4-Builder is no longer developed: its last commit dates from March 2024, and the
last npm release of `c4builder` (0.2.16) is from 2022. At Alfa-Capital it builds an architecture
repository of more than a hundred diagrams, so we continue it as a maintained fork and adapt it
to working with AI agents:

- **Deterministic offline rendering.** The PlantUML jar, the font and the engines ship with the
  package, layout is computed by Smetana (the engine built into PlantUML), Graphviz is not
  needed. The same sources produce the same SVG on a laptop, in CI and in Docker, and the build
  needs no network.
- **`c4builder check` gives feedback in seconds.** It checks individual diagrams with the same
  engine as the build and returns an exit code and the line of the error. An agent edits a
  `.puml` and immediately knows whether it broke something — without a human and without a full
  build.
- **Plugins.** `openspec` publishes specs and changes next to the C4 model, `openapi` publishes
  service contracts as offline swagger-ui pages.
- **D2** as a second diagram engine, PNG via resvg, Java is optional: c4builder downloads a JRE
  if there is none.
- **BPMN processes** as a third engine: the agent writes BPMN 2.0 XML without coordinates, the
  build checks the model and lays it out with horizontal pools and lanes.
- **Engineering basics.** TypeScript, golden snapshots of the rendering, CI on every pull
  request, an npm package and a Docker image per release tag.

The full list of changes is in the
[CHANGELOG](https://github.com/AlfaCapital-Tech/C4-Builder/blob/master/CHANGELOG.md).

## The agent loop

1. An agent (or you) edits `.md` and `.puml` files in `src/`.
2. `c4builder check <files>` tells whether the diagram compiles and shows the line of the error.
3. `c4builder --site -w` rebuilds the site on every save and reloads the browser.

Agent skills, `AGENTS.md` in a new project and `llms.txt` with diagram sources are on the
[Agents](08%20Agents/08%20Agents.md) page.

## Sections

- [Getting started](01%20Getting%20started/01%20Getting%20started.md) — installation and the first project.
- [Project](02%20Project/02%20Project.md) — how folders and files become pages.
- [Diagrams](03%20Diagrams/03%20Diagrams.md) — PlantUML, D2, BPMN, fonts, PNG, checking.
- [Outputs](04%20Outputs/04%20Outputs.md) — site, markdown per folder, single file.
- [CLI & configuration](05%20CLI%20and%20configuration/05%20CLI%20and%20configuration.md) —
  commands and `.c4builder` keys.
- [Plugins](06%20Plugins/06%20Plugins.md) — `openspec`, `openapi`, writing your own.
- [Docker & CI](07%20Docker%20and%20CI/07%20Docker%20and%20CI.md) — the image and pipeline builds.
- [Development](09%20Development/09%20Development.md) — how c4builder is built and released.
- **Design log** — the OpenSpec store of this repository: why c4builder works the way it does.

> **The Design log is in Russian.** Its pages are the project's own OpenSpec artifacts
> (proposals, designs, specs, tasks), which the team writes in Russian; they are published as
> they are, without translation. Code, identifiers and commands in them are in English.

## Credits

C4-Builder was created by Adrian Victor Lupu and is distributed under the MIT license. The fork
keeps the license, the authorship and the history: upstream changes with links to their
original pull requests are listed in the CHANGELOG.


## 01 Getting started

[Overview](#C4-Builder)

# Getting started

## Installation

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

Node.js 22.17 or newer is required. `npm install` without a tag installs the latest stable
release.

Rendering PlantUML needs Java 17+. If `java` is available in `JAVA_HOME` or on `PATH`, c4builder
uses it; otherwise the first build downloads a private JRE (Temurin) into its cache. Graphviz is
not needed: layout is computed by Smetana, the engine built into PlantUML. The PlantUML jar and
the diagram font are part of the package.

```bash
c4builder jre info      # which Java will be used (JSON: version, cache path)
c4builder jre install   # download the JRE in advance: before going offline or into a CI image
```

If you would rather not install Node and Java, use the
[Docker image](07%20Docker%20and%20CI/07%20Docker%20and%20CI.md) — it has everything.

## First project

```bash
c4builder --new --name demo -y # project from the template with a full config, no questions
cd demo
c4builder                      # build into docs/
c4builder site                 # site at http://localhost:3000
```

Without `-y`, c4builder asks for the project name, and the first build walks you through the
setup wizard. Since version 0.5.0 the shorter `c4builder new --name demo -y` works too; 0.4.0 has
no positional form, only the `--new` flag.

The new project contains the "Internet Banking System" demo from the C4 model: context,
containers, deployment, a dynamic diagram, sequence, class and ditaa diagrams, a page in Cyrillic
a D2 example and the "Account opening" BPMN process. All C4 diagrams include the library through the stdlib
(`!include <C4/C4_Container>`): C4-PlantUML is built into the jar, so the build needs no
internet. Next to `src/` there is `AGENTS.md` — instructions for AI agents on building and checking
the diagrams (since 0.5.0; it does not end up in the documentation).

## Live preview

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

Builds the project, starts a local server and rebuilds the site on every save in `src/`. The
browser reloads by itself and keeps the scroll position. `-o` opens the browser, `-p 8080`
changes the port.

## Changing the settings

`c4builder --config` (since 0.5.0 also `c4builder config`) runs the wizard again with the
current values as defaults;
`c4builder --list` prints the config. `.c4builder` is plain JSON and can be edited by hand: every
key is described on the [CLI & configuration](05%20CLI%20and%20configuration/05%20CLI%20and%20configuration.md)
page.

## Release candidates

Pre-releases `X.Y.Z-rc.N` are published under the npm tag `rc` and never touch `latest`:

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

To go back to the stable version, install the package with the `latest` tag.


## 02 Project

[Overview](#C4-Builder)

# Project

A c4builder project is a folder with a `.c4builder` file. It has two main folders: the
**sources** (`src`, key `rootFolder`) and the **output** (`docs`, key `distFolder`). Run every
command from the project folder: paths in the config are relative to it.

## Folder = page

Every folder inside the sources is one documentation page. Following the C4 model, it is usually
a system, a container or a component, but any topic works: ADRs, a glossary, a runbook.

```text
demo/
├── .c4builder              project config
├── docs/                   output: recreated on every build
└── src/                    sources
    ├── context.md          root = home page
    ├── context.puml
    ├── styles.iuml         shared diagram theme (pulled in with !include)
    └── 1 Internet Banking System/
        ├── system.md
        ├── system.puml
        └── API Application/
            ├── container.md
            └── container.puml
```

The build walks the tree and merges all `.md` files and diagrams of a folder into one page:

- **Page title** — the folder name. If the first `.md` starts with its own `# Heading`, that
  heading is used instead.
- **Page order** — file system order. To set it explicitly, use numeric prefixes:
  `1 Context`, `2 Containers`. The prefix is visible in the sidebar title.
- **Diagrams** are inserted as images. By default they go before the page text; with
  `diagramsOnTop: false`, after it.
- **A diagram can be placed anywhere in the text** by linking to its source:
  `![containers](container.puml)`. Such a diagram is not repeated in the common block.
- **Files and folders prefixed with `_`** do not become pages and are not rendered on their own,
  but they are available to `!include` and D2 imports. This is the place for shared libraries:
  `_c4lib.d2`, `_common.iuml`.
- **Other files** (images, attachments) are copied to the output next to the page unless
  `excludeOtherFiles` is on. Put an image next to the `.md` that references it.

## Service files

| File | Purpose | In git |
|---|---|---|
| `.c4builder` | project config | yes |
| `.c4builder.cache` | diagram checksums: unchanged diagrams are not rendered again | no |
| `.c4builder.lock` | build lock: two builds in one folder never write the output at the same time | no |
| `docs_bk/` | copy of the previous output during a build; kept as a fallback if the build fails | no |

c4builder deletes and recreates the output folder on every build, so do not keep your own files
there. Whether to commit the output depends on the format: markdown per folder is convenient to
keep in the repository, a site is usually built in CI.


## 03 Diagrams

[Overview](#C4-Builder)

# Diagrams

The engine is chosen by file extension: `.puml` is rendered by PlantUML, `.d2` by D2, `.bpmn`
by the BPMN engine. The formats can live in one project and even in one folder, as long as the
file names differ.

## PlantUML

c4builder runs the bundled PlantUML jar directly with `java`; layout is computed by the built-in
Smetana engine. There is no Graphviz to install. The jar version is pinned in the package, so
updating PlantUML on a developer machine does not change the build.

**C4 without internet.** The C4-PlantUML library is built into the jar; include it through the
stdlib:

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

Person(user, "Customer")
System(bank, "Internet banking")
Rel(user, bank, "Uses", "HTTPS")
@enduml
```

**Shared styles** go into an `.iuml`: `skinparam`, `UpdateElementStyle(...)`, your own macros.
Include it after the C4 include with a relative path. Paths in `!include` are relative to the
diagram's folder, not to the project root.

**Cyrillic** works in labels, descriptions and folder names: the diagram font contains it.

**ditaa** (`@startditaa`) is supported too and is always rendered as PNG.

## Diagrams inside a page

A ```` ```plantuml ```` block in an `.md` page is rendered at build time just like a `.puml`
file: the site, the markdown collection and the complete document get an image in its place,
not the block text. `@startuml`/`@enduml` may be omitted, `!include` paths are relative to the
page's folder. A broken block does not fail the build: the image is replaced by a placeholder
and the log shows a warning with the `.md` file path.

To show diagram source as code, mark the block `puml` or `text`: such blocks stay code, and
so do ```` ```d2 ```` blocks.

## Determinism and the font

Diagrams are drawn with the bundled Nimbus Sans font (Helvetica metrics, Cyrillic, Greek) rather
than a system font. The same diagram therefore has identical geometry on macOS, Linux, in CI and
in Docker, and the SVG diff in a pull request shows only real changes.

`useSystemFonts: true` in `.c4builder` (or `--system-fonts` for one run) switches to system
fonts. The look becomes more familiar, but the result depends on the machine.

## Render cache

Unchanged diagrams are not rendered again: c4builder keeps checksums in `.c4builder.cache`. A
checksum covers the source, all local `!include`s and D2 imports, the output path and the render
settings, plus the engine package versions for D2 and BPMN. Editing a shared `styles.iuml` re-renders every diagram that includes it, and only
those.

## D2

[D2](https://d2lang.com) is rendered by the WASM build of the engine right inside Node — no
external binaries. A markdown reference looks the same as for PlantUML: `![overview](landscape.d2)`.

- The engine is an optional dependency, `@terrastruct/d2` (~60 MB). npm installs it together with
  c4builder, and it is loaded only when the project contains a `.d2`. If the package is missing
  (for example, installed with `--omit=optional`), the build stops with the hint
  `npm install @terrastruct/d2`.
- [Imports](https://d2lang.com/tour/imports) `@file` and `...@file` are resolved by c4builder
  itself, no network needed. Prefix a shared class library with `_` (`_c4lib.d2`) so it is not
  rendered as a diagram of its own: `...@../_c4lib`.
- Layout is set by the `d2Layout` key: `dagre` (default) or `elk`.

## BPMN

`.bpmn` is a business process in BPMN 2.0 notation: events, tasks, gateways, horizontal pools
and lanes, message flows between participants. A markdown reference is the usual one:
`![process](process.bpmn)`.

**Only the semantics are written.** The file is standard BPMN 2.0 XML: a `collaboration` with
participants (pools) and message flows, a `process` with a `laneSet`, nodes and sequence flows.
Coordinates (the `bpmndi:BPMNDiagram` section) are not needed, and if present they are ignored:
layout is always done by the build. `incoming`/`outgoing` elements are optional, connections are
taken from `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="Request" isExecutable="false">
    <bpmn:startEvent id="Start" name="Request received" />
    <bpmn:userTask id="Check" name="Check request" />
    <bpmn:endEvent id="End" name="Request handled" />
    <bpmn:sequenceFlow id="Flow_1" sourceRef="Start" targetRef="Check" />
    <bpmn:sequenceFlow id="Flow_2" sourceRef="Check" targetRef="End" />
  </bpmn:process>
</bpmn:definitions>
```

**Example** — the account opening process from the `c4builder new` template: two pools, lanes,
messages to the credit bureau, a timer escalation. The file holds semantics only; this build did
the layout and rendering:

```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="Bank" processRef="Process_AccountOpening" />
    <bpmn:participant id="Pool_CreditBureau" name="Credit bureau" />
    <bpmn:messageFlow id="Message_HistoryRequest" name="History request"
                      sourceRef="Task_RequestHistory" targetRef="Pool_CreditBureau" />
    <bpmn:messageFlow id="Message_CreditReport" name="Credit report"
                      sourceRef="Pool_CreditBureau" targetRef="Task_ReceiveReport" />
  </bpmn:collaboration>

  <bpmn:process id="Process_AccountOpening" name="Account opening" isExecutable="false">
    <bpmn:laneSet id="LaneSet_Bank">
      <bpmn:lane id="Lane_Client" name="Customer">
        <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="Front office">
        <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="Back office">
        <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="Account needed" />
    <bpmn:userTask id="Task_SubmitApplication" name="Submit application" />
    <bpmn:userTask id="Task_CheckDocuments" name="Check documents" />
    <bpmn:sendTask id="Task_RequestHistory" name="Request credit history" />
    <bpmn:receiveTask id="Task_ReceiveReport" name="Receive credit report" />
    <bpmn:userTask id="Task_Assess" name="Assess application" />
    <bpmn:boundaryEvent id="Timer_AssessOverdue" name="3 business days" attachedToRef="Task_Assess">
      <bpmn:timerEventDefinition id="TimerDef_AssessOverdue" />
    </bpmn:boundaryEvent>
    <bpmn:task id="Task_Escalate" name="Escalate to manager" />
    <bpmn:endEvent id="End_Escalated" name="Application with manager" />
    <bpmn:exclusiveGateway id="Gateway_Decision" name="Approve?" />
    <bpmn:serviceTask id="Task_OpenAccount" name="Open account" />
    <bpmn:task id="Task_PrepareRejection" name="Prepare rejection" />
    <bpmn:endEvent id="End_AccountOpened" name="Account opened" />
    <bpmn:endEvent id="End_Rejected" name="Rejection received" />

    <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="Yes" sourceRef="Gateway_Decision" targetRef="Task_OpenAccount" />
    <bpmn:sequenceFlow id="Flow_Declined" name="No" 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>
```

**Layout** is done by [bpmn-auto-layout](https://github.com/bpmn-io/bpmn-auto-layout): pools and
lanes as horizontal bands labelled on the left, flow from left to right, every node inside the
band of its lane. Sub-processes are drawn collapsed — put their details into a separate `.bpmn`.
The layouter is still alpha: if it loses a model element, the build stops with an error listing
the element ids instead of publishing a truncated diagram. A bad layout cannot be fixed with
manual coordinates — simplify the model or split it into an overview and details.

**Rendering** uses [bpmn-js](https://bpmn.io) in the standard notation, without a browser or
network. Text is measured with the bundled Nimbus Sans, so the SVG is the same on any machine
(`useSystemFonts` does not affect BPMN); PNG comes from the regular rasterization.

**Model checks** run before layout — both in the build and in `c4builder check`. The rule set is
fixed: the recommended [bpmnlint](https://github.com/bpmn-io/bpmnlint) rules (except
`no-bpmndi`) plus the c4builder rules:

| Rule | Level | Checks |
|---|---|---|
| `no-disconnected`, `start-event-required`, `end-event-required`, `label-required`, … | error | bpmnlint recommended set |
| `c4builder/lane-membership` | error | in a process with lanes, every node is in exactly one lane |
| `c4builder/sequence-flow-in-pool` | error | a sequence flow does not cross a pool boundary |
| `c4builder/message-flow-between-pools` | error | a message flow connects different pools |
| `c4builder/gateway-flow-labels` | warning | branches of an XOR/inclusive gateway are labelled |

An error stops rendering of the diagram, a warning is only printed. Each violation is a line of
its own with the element id and the rule name:

```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
```

**Conventions:** a pool is an organization (an external one is a pool without a process, a
"black box"), a lane is a role or a unit inside it; only message flows go between pools; gateway
branches are labelled; instead of a 40+ node diagram — an overview process plus separate `.bpmn`
files for the details.

**Dependencies.** The engine packages (`bpmn-js`, `bpmn-moddle`, `bpmnlint`, `bpmn-auto-layout`,
`jsdom`) are optional: npm installs them together with c4builder, and they are loaded only when
the project contains a `.bpmn`. Installing with `--omit=optional` keeps only the core — building
a project with `.bpmn` then stops with a hint to reinstall c4builder without that flag.

## PNG

With `diagramFormat: png`, c4builder renders SVG and rasterizes it with
[resvg](https://github.com/thx/resvg-js) using the same bundled font. The PNG is consistent for
PlantUML, D2 and BPMN and needs no browser. ditaa stays a native PlantUML PNG.

## Online PlantUML server

With `generateLocalImages: false`, diagrams are not rendered locally: the output links to the
server from `plantumlServerUrl` (default `https://www.plantuml.com/plantuml`). This means diagram
sources go to an external server, and D2 and BPMN do not work in this mode — the build stops
with an error. The mode is kept for compatibility; local rendering is the main one.

## Checking individual diagrams

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

`check` validates `.puml`, `.iuml`, `.d2` and `.bpmn` files with the same engine as the build
(for `.bpmn`: parsing, rules, layout and rendering), but writes nothing and needs no project or
`.c4builder`. Exit code 0 means every file compiles, 1 means there is an error (warnings do not
affect the code):

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

`!include` is resolved from the folder of the checked file. An `.iuml` library is checked by
including it into an empty diagram, and an `.iuml` with C4 macros (`UpdateElementStyle` and the
like) — in the context of the C4 stdlib, as in the diagrams that include it. No line number is
printed for an `.iuml`.

A pre-commit hook that checks staged diagrams (`.git/hooks/pre-commit`; spaces in paths are
fine):

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


## 04 Outputs

[Overview](#C4-Builder)

# Outputs

Output formats are switched on independently, in any combination: the wizard asks about them on
the first build, and in `.c4builder` they are `generateMD`, `generateCompleteMD` and
`generateWEB`. The output mirrors the structure of the sources.

## Docsify site

`generateWEB: true` (default). The output gets an `index.html`, a sidebar with the page hierarchy
and one `.md` per page. The site is static and does not go to the internet: docsify, the theme
and the plugins sit in `vendor/` next to `index.html`, diagrams are ready-made SVG or PNG files.
Theme fonts are system fonts (no Google Fonts), emoji such as `:smile:` are shown as characters
rather than images from GitHub, and ```` ```plantuml ```` blocks are rendered at build time, not
in the browser via plantuml.com. External addresses appear only by explicit choice:
`generateLocalImages: false` (diagram images link to `plantumlServerUrl`), a custom `webTheme`
or `docsifyTemplate` that uses them, external images in page text.

- To view it locally, run `c4builder site` (or `--site -w` to rebuild on changes), by default at
  `http://localhost:3000`. Double-clicking `index.html` will not work: docsify loads pages with
  requests and needs an HTTP server.
- To publish it, copy the output folder to any static hosting: GitHub Pages, GitLab Pages,
  nginx. The build writes `.nojekyll` so GitHub Pages does not hide files starting with `_`.
- Site search is `supportSearch`, the repository link in the corner is `repoUrl`, a custom theme
  is `webTheme`, a custom `index.html` template is `docsifyTemplate`.

This site is an example of such an output: see [Docker & CI](07%20Docker%20and%20CI/07%20Docker%20and%20CI.md)
for how it is built.

## llms.txt for agents

`generateLLMS: true` (since 0.5.0, needs the site) puts `llms.txt` — an index of links to the pages'
`.md` files — and `llms-full.txt` — the full text with diagrams inserted as source — into the site
root. Details are on the [Agents](08%20Agents/08%20Agents.md) page.

## Markdown per folder

`generateMD: true` (default). Each output folder gets a `README.md` with all the text and
diagrams of the page. This output is convenient to commit: GitHub and GitLab render it as regular
repository documentation.

Navigation at the top of each file:

- `includeTableOfContents` (default) — the tree of all pages with the current one highlighted;
- `includeNavigation` — a link to the parent and a list of child pages.

## Single file

`generateCompleteMD: true` puts everything into `<projectName>.md` at the output root: a table of
contents followed by a section per page, each with a link back to the top. It works as a single
architecture README or as input for tools that read one file.

## How diagrams appear

| Key | What it changes |
|---|---|
| `diagramsOnTop` | diagrams not placed in the text explicitly go before the text (default) or after it |
| `includeLinkToDiagram` | a link to the diagram file instead of the image |
| `embedDiagram` | the image is embedded into markdown as a base64 string, with a download link next to it |
| `includeBreadcrumbs` | the page's path in the tree under its title |
| `excludeOtherFiles` | do not copy images and other files from the sources to the output |
| `diagramFormat` | `svg` (default) or `png` |


## 05 CLI and configuration

[Overview](#C4-Builder)

# CLI & configuration

## Commands

| Command | What it does |
|---|---|
| `c4builder` | builds the project in the current folder; without a config it runs the wizard first |
| `c4builder --new` | creates a project from the template in a new folder; since 0.5.0 also `c4builder new` |
| `c4builder --new --name demo -y` | the same without questions: a full config with default values |
| `c4builder --config` | setup wizard with the current values; since 0.5.0 also `c4builder config` |
| `c4builder site` | builds and serves the site locally (same as `--site`) |
| `c4builder --site -w` | the same, rebuilding on every save and reloading the browser |
| `c4builder check <files...>` | checks `.puml`, `.iuml`, `.d2`, `.bpmn` diagrams without a build, exit code 0 or 1 |
| `c4builder jre info` | which Java will be used (JSON) |
| `c4builder jre install [--force]` | download a JRE into the cache in advance; `--force` — even if system Java exists |
| `c4builder --list` | print the current config; since 0.5.0 outside a project — an error with exit code 1, no files created |
| `c4builder --reset` | clear the project config; since 0.5.0 outside a project — an error with exit code 1 |
| `c4builder --docs` | short reference of config keys and the address of this documentation |

Positional commands are `check`, `jre`, `site`, and since 0.5.0 also `new` and `config`. Since
0.5.0 any other positional argument is an `unknown command` error with exit code 1: a typo
(`c4builder nwe`) no longer starts a build.

Flags:

| Flag | Meaning |
|---|---|
| `-c, --config-file <path>` | a different config file instead of `.c4builder` |
| `-w, --watch` | rebuild on changes in the sources and plugin folders |
| `-o, --open` | open the site in the browser (with `--site`) |
| `-p, --port <n>` | port for `--site` (defaults to `webPort` from the config, 3000) |
| `--system-fonts` | render with system fonts for one run |
| `-V, --version` | version |

## How the config is read

`.c4builder` is JSON in the project folder. The first build asks for missing keys through the
wizard and sets `hasRun: true`; after that, `c4builder` builds without questions. `new -y` writes
a full config right away, so there is no wizard at all.

Keys are validated against a schema. A value of the wrong type stops the build with an error
naming the key, and `c4builder --config` lets you fix it. Unknown keys are silently dropped — this
way an older c4builder does not fail on a config written by a newer one. Keys of features removed
in older versions produce a warning listing them, and the build continues.

## `.c4builder` keys

| Key | Default | What it sets |
|---|---|---|
| `projectName` | name given at creation | project name: title of the site and of the single file |
| `homepageName` | `Overview` | title of the root page |
| `rootFolder` | `src` | sources folder |
| `distFolder` | `docs` | output folder, recreated on every build |
| `generateWEB` | `true` | docsify site |
| `generateMD` | `true` | markdown per folder |
| `generateCompleteMD` | `false` | single `<projectName>.md` file |
| `generateLLMS` | `true` in new projects, off when absent | `llms.txt` and `llms-full.txt` for agents, needs `generateWEB` (since 0.5.0) |
| `includeTableOfContents` | `true` | page tree at the top of each markdown file |
| `includeNavigation` | `false` | links to the parent and child pages in markdown |
| `includeBreadcrumbs` | `true` | page path under the title |
| `diagramsOnTop` | `true` | diagrams before the page text |
| `includeLinkToDiagram` | `false` | a link instead of the diagram image |
| `embedDiagram` | `false` | image embedded in markdown as base64 |
| `excludeOtherFiles` | `false` | do not copy other files from the sources |
| `generateLocalImages` | `true` | local rendering; `false` — links to an online server |
| `plantumlServerUrl` | `https://www.plantuml.com/plantuml` | server for `generateLocalImages: false` |
| `diagramFormat` | `svg` | `svg` or `png` |
| `d2Layout` | `dagre` | D2 layout: `dagre` or `elk` |
| `useSystemFonts` | `false` | system fonts instead of the bundled one |
| `charset` | `UTF-8` | encoding of PlantUML sources |
| `webTheme` | `vendor/vue.css` | docsify CSS theme |
| `supportSearch` | `true` | search in the sidebar |
| `repoUrl` | empty | repository link in the corner of the site |
| `executeScript` | `false` | run `<script>` in pages and load swagger-ui |
| `docsifyTemplate` | empty | path to a module with a custom `index.html` template |
| `webPort` | `3000` | port of `c4builder site` |
| `webFileName` | — | one `.md` name for all site pages instead of the folder name |
| `excludeSidebarFolderByPath` | — | list of paths (from the project folder, e.g. `src/Archive`) hidden from the sidebar |
| `plugins` | `[]` | build plugins, see [Plugins](06%20Plugins/06%20Plugins.md) |

The config of this documentation site is a live example: `docs/en/.c4builder` in the repository.

## Custom docsify template

`docsifyTemplate` points to an ESM or CommonJS module that exports a function. The function
receives the docsify settings object (name, sidebar, theme, search) and returns the HTML for
`index.html`. Start from the built-in template in `src/core/compose/docsify.template.ts`; this
site uses its own, `docs/docsify-template.mjs`.


## 06 Plugins

[Overview](#C4-Builder)

# Plugins

Plugins add content from outside `rootFolder` to the build — virtual pages — and site assets.
Virtual pages go through the regular pipeline: sidebar, search, markdown per folder, the single
file, local diagram rendering.

Plugins are listed in `.c4builder` under the `plugins` key — either as `"name"` or as
`["name", { ...options }]`:

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

A plugin identifier resolves in this order: a built-in name (`openspec`, `openapi`) → a local
ESM module (`./plugins/my.mjs`, `../shared/plugin.mjs`, an absolute path) → an npm package
resolved from the project folder.

- Options are validated by the plugin's schema **before** the build starts. Built-in plugins are
  strict: an unknown option key is an error.
- `${ENV_VAR}` in string options is replaced with the environment variable (unset — empty
  string) and is never printed. Archive URLs appear in messages without their query string, so a
  token in `?private_token=${TOKEN}` stays out of the logs.
- A malformed `plugins` entry always fails the build: it is the one key the wizard cannot repair.
- Older c4builder versions ignore the `plugins` key, so rolling back does not break the build.

## `openspec` — a design log on the site

Publishes an [OpenSpec](https://github.com/Fission-AI/OpenSpec) store as a site section: a
summary (counters, task progress), a page per active change, the specs tree and the archive. The
"Design log" section of this site is built exactly this way, from the repository's `openspec/`
folder.

- A change page shows a header (schema, dates, task progress, links to subpages) and the first
  artifact from `artifacts` — `proposal` by default, so the "why" is visible without an extra
  click. The remaining artifacts (`design`, `tasks`, then other `*.md` alphabetically) are
  subpages; spec deltas live under `specs/…` with the same folder layout.
- ```` ```plantuml ````, ```` ```puml ```` and ```` ```d2 ```` blocks inside artifacts are
  rendered by the **local** engines; nothing is sent to plantuml.com. The image name is derived
  from the block content, so inserting or reordering blocks never picks up a neighbour's cached
  image.
- A block that fails to render does not fail the build: the page gets a placeholder and the
  build prints a warning naming the artifact file.
- Relative links between artifacts point to their pages; files referenced by artifacts (images,
  notes) are copied next to the page.
- In `-w` mode the store folder is watched too.

| Option | Default | Meaning |
|---|---|---|
| `dir` | `openspec` | store folder (relative to the project folder) |
| `mount` | `OpenSpec` | section name and its path in the output |
| `artifacts` | `["proposal","design","tasks"]` | artifact order; the first one is shown on the change page |

## `openapi` — swagger-ui for a set of specs

Finds specs by `glob` in a local folder (`dir`) **or** in a `tar.gz`/`zip` archive downloaded
over HTTP (`archive` — for example, a GitLab or GitHub repository archive URL). One page per
spec, named after the spec's parent folder (after the file name for specs in the source root),
plus an index.

- All `yaml`/`yml`/`json` files of the source are copied into `<mount>/_specs/…` keeping their
  layout, so relative `$ref`s (including shared schema files that do not match `glob`) keep
  resolving.
- Pages load swagger-ui from the bundled files: no CDN, no external spec validator (the
  `validator.swagger.io` badge is off), and readers need no access to the source repository.
- The plugin turns `executeScript` on (and logs it) and adds `swagger-ui.css` and
  `swagger-ui-bundle.js` to `index.html`, so a custom `docsifyTemplate` needs no change.
- The archive is downloaded once per process and reused in `-w` mode.
- Behind a TLS-intercepting proxy the download fails with `self-signed certificate in certificate
  chain` — point `NODE_EXTRA_CA_CERTS` at the CA bundle (Node reads neither the system store nor
  `SSL_CERT_FILE`). The error message says so as well.

| Option | Default | Meaning |
|---|---|---|
| `mount` | `API` | section name |
| `dir` | — | local folder with specs (watched in `-w`) |
| `archive` | — | HTTP(S) URL of a tar.gz/zip archive |
| `subdir` | — | folder inside the archive or `dir` |
| `headers` | — | HTTP headers for the archive request; empty values are dropped |
| `glob` | `**/openapi.{yaml,yml,json}` | spec pattern (`**`, `*`, `?`, `{a,b}`); directories starting with a dot are skipped |

Example: the OpenSpec store sits next to the C4 sources, and contracts come from another
repository. An empty `GITLAB_TOKEN` drops the header, so the same config works with and without a
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}" }
    }]
  ]
}
```

## Writing a plugin

A plugin is an ESM module whose default export is a plain object. For typing, use
`definePlugin` from `@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(), // optional
  watchPaths: (opts) => [opts.file],                                          // optional
  assets: { styles: ['/abs/path/x.css'], scripts: ['/abs/path/x.js'] },      // optional
  requires: { executeScript: true },                                          // optional
  async afterScan(ctx, opts) {
    // ctx.tree, ctx.options — the build tree and options; ctx.source({ dir } | { archive, subdir, headers })
    // resolves a source folder; ctx.addPage adds a virtual page
    // (missing parents become index pages).
    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 — copy extra files, check the output */ }
};
```

Hooks run in the order of the `plugins` list. An exception in a hook aborts the build with the
plugin's name; the copy of the previous output is kept. A virtual page path cannot coincide with
a real source folder — the build stops and asks you to rename the `mount`.


## 07 Docker and CI

[Overview](#C4-Builder)

# Docker & CI

## Docker image

The image has everything a build needs: Node, a JRE, the PlantUML jar, fonts, D2 and the BPMN engine. Mount the
project into `/pwd`:

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

Checking diagrams without installing anything:

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

Image tags are in sync with npm tags:

| Tag | What it is |
|---|---|
| `X.Y.Z`, `sha-…` | immutable: a specific release or commit |
| `X.Y` | latest patch of a stable line |
| `latest` | latest stable release |
| `rc` | latest release candidate |
| `edge` | latest commit on `master` |
| `pr-N` | pull request builds |

For reproducible CI builds, pin `X.Y.Z`: a different PlantUML version may shift diagram layout.

## Building in CI

The image can be used directly as the job image: `c4builder` is on `PATH`.

GitLab CI, checking diagrams and publishing to GitLab Pages (`.c4builder` has
`"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 without Docker: Node from `setup-node`, Java from `setup-java` (or let c4builder
download a JRE itself):

```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
```

If the runner has no Java, c4builder downloads a JRE on the first build. To avoid downloading it
every time, cache the folder reported by `c4builder jre info` (the `cacheDir` field) and warm it
up with `c4builder jre install` on a cache miss.

The build behaves in CI just like locally: the exit code is not 0 if even one diagram fails to
render. A separate quick `c4builder check` step on changed files reports a clear error before the
full build.

## How this site is built

The `.github/workflows/pages.yml` workflow in the c4builder repository builds the CLI from the
same commit, then `docs/ru` and `docs/en` as two separate projects, puts them together with the
landing page into one artifact and publishes it to GitHub Pages from `master` only. On pull
requests the site is built but not published — a broken diagram in the docs shows up before the
merge.


## 08 Agents

[Overview](#C4-Builder)

# Agents

An agent edits a C4 model in text form as confidently as code: `Person`, `System`, `Container`
and `Rel` in a `.puml` are a ready-made semantic model, not a picture. What it usually lacks is
something else: a fast, unambiguous answer to "did I break it?". c4builder gives that answer
locally, without a network and without a human.

## The edit → check → build loop

1. **Edit.** The agent changes `.md` and `.puml`/`.d2`/`.bpmn` files in `src/` — adds a
   container, a relationship, a page, a process step.
2. **Check.** `c4builder check` on the changed files:

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

   Exit code 0 — everything compiles. Exit code 1 — the output has a line with the file and the
   line number:

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

   The check uses the same engine and the same `!include`s as the build and takes seconds: the
   agent fixes the error and repeats until it gets 0. For `.bpmn`, every model violation is a
   line with the element id and the rule: `✗ <file>: <id> [<rule>] <description>`.
3. **Build.** `c4builder` builds the whole project; `c4builder --site -w` keeps the site open for
   the human and rebuilds it on every save the agent makes.

A full build also exits with a non-zero code if any diagram fails to render, so it can be the
agent's last step or a CI step.

## Why offline rendering matters for agents

- **No network, no random failures.** The PlantUML jar, the C4 library, the font, D2 and the BPMN
  engine ship with the package; the build does not depend on plantuml.com, proxies or rate limits.
- **Same input, same output.** The bundled font and pinned engine versions give identical SVG on
  any machine. The pull request diff shows what the agent changed in the model, not
  environmental noise.
- **Sources stay inside.** Architecture often contains things that do not belong on someone
  else's server; local rendering rules that out.

## Agent skills

c4builder ships [Agent Skills](https://agentskills.io) for Claude Code, Codex, Cursor and the other
agents supported by the [`skills`](https://github.com/vercel-labs/skills) CLI. The skills live in
the `skills/` folder of the repository (they are not part of the npm package) and describe the
latest stable release, so their commands use the flags: `--new`, `--config`.

```bash
npx skills add AlfaCapital-Tech/C4-Builder/skills                    # both skills into the current project
npx skills add AlfaCapital-Tech/C4-Builder/skills --skill c4builder  # just one
```

`-g` installs the skills for the user instead of the project. The `/skills` path in the command
matters: without it the CLI also picks up the internal development skills of c4builder itself
from `.claude/skills/`.

| Skill | Use it for |
|---|---|
| `c4builder` | working on a project: layout of `src/` and `.c4builder`, the edit → `c4builder check` → build loop, C4-PlantUML conventions (stdlib includes, shared `.iuml`, offline rendering), D2, BPMN processes without coordinates, the `openspec` and `openapi` plugins, `llms.txt` |
| `c4builder-setup` | install and update (npm channels `latest` and `rc`, the Docker image), Java or the downloaded JRE, a smoke build of the template project |

## AGENTS.md in a new project

Since version 0.5.0, `c4builder --new` puts an `AGENTS.md` into the project: build and check
commands, the workflow, the project layout, diagram conventions and the skills install command.
Codex, Cursor and Claude Code read it. The file sits next to `src/`, not inside it, and does not
end up in the documentation.

## llms.txt: architecture an agent can read

With `"generateLLMS": true` (since version 0.5.0, needs `generateWEB`) the site root gets two more
files following [llmstxt.org](https://llmstxt.org/):

- **`llms.txt`** — the entry point: the project name, a short description and a flat list of pages
  in sidebar order, like `- [System / Container](System/Container/Container.md)`. Folders from
  `excludeSidebarFolderByPath` are left out, plugin pages (such as `openspec`) are included. Links
  are relative to the site root.
- **`llms-full.txt`** — the full text of all pages in one file, in the same order as the single
  markdown file. Every diagram is inserted as its **source** in a `plantuml`, `d2` or `xml` (BPMN) block instead
  of an image, regardless of `diagramFormat`, `embedDiagram` and `includeLinkToDiagram`. Local
  `!include` files and D2 imports (nested ones too) are listed once in the `## Included files`
  appendix at the end; stdlib includes `!include <C4/...>` and URL includes stay as lines in the
  diagram source.

The source is more useful than a picture: C4-PlantUML text (`Person`, `System`, `Rel`) is a
ready-made model, while an SVG link gives an agent nothing. To answer "what does service X depend
on", an agent can read `llms-full.txt` instead of crawling pages.

Without the site the build prints a warning and skips the files. New projects have the key on; an
existing `.c4builder` without the key builds as before — enable it with `c4builder --config` or by
adding `"generateLLMS": true` to the config.

Files of this site:

| | Russian version | English version |
|---|---|---|
| Index | [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) |
| Full text | [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) |

## Hints for agent instructions

A project created before 0.5.0 has no `AGENTS.md`. What to put into `AGENTS.md` or `CLAUDE.md` of
such a project:

- after editing a diagram — `c4builder check <file>`, fix until exit code 0;
- include C4 through the stdlib (`!include <C4/C4_Container>`), shared styles with
  `!include ../styles.iuml`;
- a new page is a new folder in `src/`, the order is set by a numeric prefix;
- `.puml`, `.d2` and `.bpmn` files in one folder must not share a name ignoring the extension: they share
  the output file, and the build stops with an error.

Add the pre-commit hook from the [Diagrams](03%20Diagrams/03%20Diagrams.md) page: it keeps a
diagram that does not compile out of a commit, whether a human or an agent made it.


## 09 Development

[Overview](#C4-Builder)

# Development

This page is for those who change c4builder itself. Repository:
[AlfaCapital-Tech/C4-Builder](https://github.com/AlfaCapital-Tech/C4-Builder).

## How it works

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

LAYOUT_TOP_DOWN()

Person(user, "Developer or agent", "Runs the CLI in a project folder")

System_Boundary(c4b, "C4-Builder") {
    Container(cli, "CLI", "TypeScript, commander", "src/cli: argument parsing, setup wizard, commands new, config, check, jre, site")
    Container(config, "Config", "TypeScript, zod", "src/config: .c4builder schema, defaults, build options")
    Container(scan, "scan", "TypeScript", "src/core/scan: walks src/, builds the tree of pages and diagrams")
    Container(plugins, "Plugins", "TypeScript", "src/core/plugins + src/plugins: hooks, virtual pages; built-in openspec and openapi")
    Container(render, "render", "TypeScript", "src/core/render: PlantUML via java, D2 via WASM, PNG via resvg, checksum cache")
    Container(compose, "compose", "TypeScript", "src/core/compose: markdown pages, sidebar, docsify index.html")
    ContainerDb(vendor, "vendor/", "Files", "PlantUML jar, Nimbus Sans fonts, docsify, swagger-ui")
}

System_Ext(java, "Java 17+", "System java or a JRE downloaded by c4builder (Temurin)")
System_Ext(out, "Build output", "dist: site, markdown, SVG/PNG")

Rel(user, cli, "Runs")
Rel(cli, config, "Reads .c4builder")
Rel(cli, scan, "Starts the build")
Rel(scan, plugins, "afterScan: plugin pages")
Rel(scan, render, "Tree")
Rel(render, compose, "Rendered diagrams")
Rel(render, java, "Runs PlantUML", "java -jar")
Rel(render, vendor, "jar, font")
Rel(compose, out, "Writes")
Rel(compose, vendor, "docsify")

SHOW_LEGEND()
@enduml
```

The build runs in phases: **scan** walks `src/` and builds the page tree, **plugins** add virtual
pages to it, **render** renders the diagrams (with a checksum cache), **compose** writes markdown,
the sidebar and `index.html`. The CLI is a thin layer on top: argument parsing, the wizard, and
the separate `check` and `jre` commands. Everything that affects the rendering result (the
PlantUML jar, fonts, docsify, swagger-ui) lives in `vendor/` and is not edited by hand.

## Build and tests

```bash
npm ci
npm run build          # tsc → dist/
npm test               # all tests, including golden
npm run test:unit      # without golden: fast and Java-free
npm run check          # biome: lint and format
```

TypeScript, ESM, Node 22.17+. The tests run the built CLI from `dist/`, so `npm test` compiles
first.

**Output language.** Everything the CLI prints for the user is in English; code comments are in
Russian. The `test/cli-language.test.mjs` test fails on Cyrillic in string literals under `src/`.

**Golden snapshots.** `test/golden.test.mjs` builds the `template/src` template in several
configurations and compares the whole output with the reference in `test/golden/` —
byte-for-byte, SVG included. Rendering is pinned to a specific JRE (Temurin), which the test
downloads into the cache itself. Changed the rendering or the template? Regenerate the references
with `npm run test:golden:update` and include the `test/golden/` diff in the pull request. On some
Linux distributions the SVGs differ because of the system fontconfig; in CI on Ubuntu the
reference is stable.

**Documentation site.** Sources are in `docs/ru/src` and `docs/en/src`, the landing page in
`docs/landing`. The `test/docs-parity.test.mjs` test checks that RU and EN have the same set of
pages: folders are matched by numeric prefix, files by name. Local preview:

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

## Process: OpenSpec

Behaviour changes are first described in [OpenSpec](https://github.com/Fission-AI/OpenSpec):
`openspec/changes/<name>/` holds the proposal (why), the design (how and why this way), specs
(requirements with scenarios) and tasks. After implementation the change is archived and its
requirements move to `openspec/specs/`. Artifacts are written in Russian; code and identifiers in
English.

The whole store is published on this site in the **Design log** section: active changes, specs
and the archive — the offline template, dropping Graphviz, local D2 and PNG rendering, the move
to TypeScript, the plugin system. Its pages are in Russian.

## Changelog

Every user-facing change (a feature, a fix, CLI behaviour) adds a line to the `## Unreleased`
section of [CHANGELOG.md](https://github.com/AlfaCapital-Tech/C4-Builder/blob/master/CHANGELOG.md)
in the same pull request. If behaviour changes, the page on this site is updated too — in both
language versions.

## Releases

Only pushing a git tag `v<version>` publishes anything. A merge to `master` publishes nothing
except the `edge` Docker tag and an update of this site.

**Release candidate** — from `master`, as many as needed; whoever follows `rc` gets each one:

```bash
npm version X.Y.Z-rc.1 -m "rc: %s"      # first candidate
npm version prerelease -m "rc: %s"      # next ones: rc.2, rc.3, …
git push --follow-tags
```

Publishes to the npm tag `rc` and the Docker tag `rc`; `latest` is untouched.

**Final release** — first rename `## Unreleased` to `## vX.Y.Z` in `CHANGELOG.md`:

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

Publishes to the npm tag `latest` and the Docker tags `X.Y.Z`, `X.Y`, `latest`. npm is published
via OIDC (trusted publishing) with provenance, the image goes to GHCR.


## Design log

[Overview](#C4-Builder)

**Active changes:** [0](Design%20log/Changes/Changes) · **Specs:** [19](Design%20log/Specs/Specs) · **Archived:** [29](Design%20log/Archive/Archive) · **Tasks:** —

## Active changes

_No changes._

## Changes

[Overview](#C4-Builder)

_No changes._

## Specs

[Overview](#C4-Builder)

- [agent-skills](Design%20log/Specs/agent-skills/agent-skills)
- [bpmn-diagrams](Design%20log/Specs/bpmn-diagrams/bpmn-diagrams)
- [build-pipeline](Design%20log/Specs/build-pipeline/build-pipeline)
- [ci-validation](Design%20log/Specs/ci-validation/ci-validation)
- [cli-commands](Design%20log/Specs/cli-commands/cli-commands)
- [config-validation](Design%20log/Specs/config-validation/config-validation)
- [dev-toolchain](Design%20log/Specs/dev-toolchain/dev-toolchain)
- [diagram-rendering](Design%20log/Specs/diagram-rendering/diagram-rendering)
- [docs-site](Design%20log/Specs/docs-site/docs-site)
- [jre-resolution](Design%20log/Specs/jre-resolution/jre-resolution)
- [offline-site](Design%20log/Specs/offline-site/offline-site)
- [openapi-plugin](Design%20log/Specs/openapi-plugin/openapi-plugin)
- [openspec-plugin](Design%20log/Specs/openspec-plugin/openspec-plugin)
- [output-formats](Design%20log/Specs/output-formats/output-formats)
- [plugin-system](Design%20log/Specs/plugin-system/plugin-system)
- [project-scaffold](Design%20log/Specs/project-scaffold/project-scaffold)
- [project-template](Design%20log/Specs/project-template/project-template)
- [regression-testing](Design%20log/Specs/regression-testing/regression-testing)
- [release-publishing](Design%20log/Specs/release-publishing/release-publishing)

## agent-skills

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

## 2026-10-06-docs-site

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-06-docs-site/design/design) · [tasks](Design%20log/Archive/2026-10-06-docs-site/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [docs-site](Design%20log/Archive/2026-10-06-docs-site/specs/docs-site/docs-site)

## docs-site

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-06-bpmn-diagrams/design/design) · [tasks](Design%20log/Archive/2026-10-06-bpmn-diagrams/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [bpmn-diagrams](Design%20log/Archive/2026-10-06-bpmn-diagrams/specs/bpmn-diagrams/bpmn-diagrams)
- [diagram-rendering](Design%20log/Archive/2026-10-06-bpmn-diagrams/specs/diagram-rendering/diagram-rendering)
- [project-template](Design%20log/Archive/2026-10-06-bpmn-diagrams/specs/project-template/project-template)
- [regression-testing](Design%20log/Archive/2026-10-06-bpmn-diagrams/specs/regression-testing/regression-testing)

## bpmn-diagrams

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[tasks](Design%20log/Archive/2026-10-03-pr8-review-fixes/tasks/tasks) · [README](Design%20log/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

[Overview](#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

[Overview](#C4-Builder)

# pr8-review-fixes

Починка находок max-ревью PR #8: 15 верифицированных дефектов TS-порта (регрессии конфига, lifecycle сборки, JRE, compose)

## 2026-10-03-plugin-system

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-plugin-system/design/design) · [tasks](Design%20log/Archive/2026-10-03-plugin-system/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [openapi-plugin](Design%20log/Archive/2026-10-03-plugin-system/specs/openapi-plugin/openapi-plugin)
- [openspec-plugin](Design%20log/Archive/2026-10-03-plugin-system/specs/openspec-plugin/openspec-plugin)
- [plugin-system](Design%20log/Archive/2026-10-03-plugin-system/specs/plugin-system/plugin-system)

## openapi-plugin

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[tasks](Design%20log/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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-offline-site-assets/design/design) · [tasks](Design%20log/Archive/2026-10-03-offline-site-assets/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [offline-site](Design%20log/Archive/2026-10-03-offline-site-assets/specs/offline-site/offline-site)
- [openapi-plugin](Design%20log/Archive/2026-10-03-offline-site-assets/specs/openapi-plugin/openapi-plugin)

## offline-site

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-node-22/design/design) · [tasks](Design%20log/Archive/2026-10-03-node-22/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [dev-toolchain](Design%20log/Archive/2026-10-03-node-22/specs/dev-toolchain/dev-toolchain)

## dev-toolchain

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-llms-txt/design/design) · [tasks](Design%20log/Archive/2026-10-03-llms-txt/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [output-formats](Design%20log/Archive/2026-10-03-llms-txt/specs/output-formats/output-formats)
- [project-scaffold](Design%20log/Archive/2026-10-03-llms-txt/specs/project-scaffold/project-scaffold)

## output-formats

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-cli-fixes/design/design) · [tasks](Design%20log/Archive/2026-10-03-cli-fixes/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [cli-commands](Design%20log/Archive/2026-10-03-cli-fixes/specs/cli-commands/cli-commands)

## cli-commands

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-cli-english-messages/design/design) · [tasks](Design%20log/Archive/2026-10-03-cli-english-messages/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [cli-commands](Design%20log/Archive/2026-10-03-cli-english-messages/specs/cli-commands/cli-commands)

## cli-commands

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-10-03-agent-skills/design/design) · [tasks](Design%20log/Archive/2026-10-03-agent-skills/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [agent-skills](Design%20log/Archive/2026-10-03-agent-skills/specs/agent-skills/agent-skills)
- [cli-commands](Design%20log/Archive/2026-10-03-agent-skills/specs/cli-commands/cli-commands)
- [project-template](Design%20log/Archive/2026-10-03-agent-skills/specs/project-template/project-template)

## agent-skills

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-24-nimbus-font-system-flag/design/design) · [tasks](Design%20log/Archive/2026-07-24-nimbus-font-system-flag/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [diagram-rendering](Design%20log/Archive/2026-07-24-nimbus-font-system-flag/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-09-tag-driven-rc-publish/design/design) · [tasks](Design%20log/Archive/2026-07-09-tag-driven-rc-publish/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [release-publishing](Design%20log/Archive/2026-07-09-tag-driven-rc-publish/specs/release-publishing/release-publishing)

## release-publishing

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-08-zod-and-deps-upgrade/design/design) · [tasks](Design%20log/Archive/2026-07-08-zod-and-deps-upgrade/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [config-validation](Design%20log/Archive/2026-07-08-zod-and-deps-upgrade/specs/config-validation/config-validation)
- [dev-toolchain](Design%20log/Archive/2026-07-08-zod-and-deps-upgrade/specs/dev-toolchain/dev-toolchain)

## config-validation

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-07-ts-port-full/design/design) · [tasks](Design%20log/Archive/2026-07-07-ts-port-full/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [build-pipeline](Design%20log/Archive/2026-07-07-ts-port-full/specs/build-pipeline/build-pipeline)

## build-pipeline

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-07-build-split/design/design) · [tasks](Design%20log/Archive/2026-07-07-build-split/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [build-pipeline](Design%20log/Archive/2026-07-07-build-split/specs/build-pipeline/build-pipeline)

## build-pipeline

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-ts-scaffold/design/design) · [tasks](Design%20log/Archive/2026-07-05-ts-scaffold/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [build-pipeline](Design%20log/Archive/2026-07-05-ts-scaffold/specs/build-pipeline/build-pipeline)
- [ci-validation](Design%20log/Archive/2026-07-05-ts-scaffold/specs/ci-validation/ci-validation)
- [dev-toolchain](Design%20log/Archive/2026-07-05-ts-scaffold/specs/dev-toolchain/dev-toolchain)

## build-pipeline

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-resvg-png/design/design) · [tasks](Design%20log/Archive/2026-07-05-resvg-png/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [diagram-rendering](Design%20log/Archive/2026-07-05-resvg-png/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-remove-vscode-snippets/design/design) · [tasks](Design%20log/Archive/2026-07-05-remove-vscode-snippets/tasks/tasks) · [README](Design%20log/Archive/2026-07-05-remove-vscode-snippets/README/README) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

# remove-vscode-snippets

Полное удаление VSCode-сниппетов из c4builder --new

## specs

[Overview](#C4-Builder)

- [project-scaffold](Design%20log/Archive/2026-07-05-remove-vscode-snippets/specs/project-scaffold/project-scaffold)

## project-scaffold

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-remove-plantuml-version/design/design) · [tasks](Design%20log/Archive/2026-07-05-remove-plantuml-version/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [diagram-rendering](Design%20log/Archive/2026-07-05-remove-plantuml-version/specs/diagram-rendering/diagram-rendering)

## diagram-rendering

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-remove-pdf/design/design) · [tasks](Design%20log/Archive/2026-07-05-remove-pdf/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [output-formats](Design%20log/Archive/2026-07-05-remove-pdf/specs/output-formats/output-formats)

## output-formats

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-new-noninteractive/design/design) · [tasks](Design%20log/Archive/2026-07-05-new-noninteractive/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [project-scaffold](Design%20log/Archive/2026-07-05-new-noninteractive/specs/project-scaffold/project-scaffold)

## project-scaffold

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-jre-resolver/design/design) · [tasks](Design%20log/Archive/2026-07-05-jre-resolver/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [diagram-rendering](Design%20log/Archive/2026-07-05-jre-resolver/specs/diagram-rendering/diagram-rendering)
- [jre-resolution](Design%20log/Archive/2026-07-05-jre-resolver/specs/jre-resolution/jre-resolution)

## diagram-rendering

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-golden-matrix/design/design) · [tasks](Design%20log/Archive/2026-07-05-golden-matrix/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [regression-testing](Design%20log/Archive/2026-07-05-golden-matrix/specs/regression-testing/regression-testing)

## regression-testing

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-dev-toolchain/design/design) · [tasks](Design%20log/Archive/2026-07-05-dev-toolchain/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [ci-validation](Design%20log/Archive/2026-07-05-dev-toolchain/specs/ci-validation/ci-validation)
- [dev-toolchain](Design%20log/Archive/2026-07-05-dev-toolchain/specs/dev-toolchain/dev-toolchain)

## ci-validation

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-05-d2-backend/design/design) · [tasks](Design%20log/Archive/2026-07-05-d2-backend/tasks/tasks) · [README](Design%20log/Archive/2026-07-05-d2-backend/README/README) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

# d2-backend

D2 как второй бэкенд рендера диаграмм (@terrastruct/d2 WASM → SVG) рядом с PlantUML: .d2-файлы, импорты через виртуальную fs, C4-поддержка

## specs

[Overview](#C4-Builder)

- [diagram-rendering](Design%20log/Archive/2026-07-05-d2-backend/specs/diagram-rendering/diagram-rendering)
- [regression-testing](Design%20log/Archive/2026-07-05-d2-backend/specs/regression-testing/regression-testing)

## diagram-rendering

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-04-template-offline/design/design) · [tasks](Design%20log/Archive/2026-07-04-template-offline/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [project-template](Design%20log/Archive/2026-07-04-template-offline/specs/project-template/project-template)

## project-template

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-04-plantuml-java-direct/design/design) · [tasks](Design%20log/Archive/2026-07-04-plantuml-java-direct/tasks/tasks) · [README](Design%20log/Archive/2026-07-04-plantuml-java-direct/README/README) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

# plantuml-java-direct

Прямой вызов java со Smetana вместо node-plantuml: отказ от внешнего graphviz, детерминированный рендер через vendored-шрифт

## specs

[Overview](#C4-Builder)

- [ci-validation](Design%20log/Archive/2026-07-04-plantuml-java-direct/specs/ci-validation/ci-validation)
- [diagram-rendering](Design%20log/Archive/2026-07-04-plantuml-java-direct/specs/diagram-rendering/diagram-rendering)
- [regression-testing](Design%20log/Archive/2026-07-04-plantuml-java-direct/specs/regression-testing/regression-testing)

## ci-validation

[Overview](#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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

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

[design](Design%20log/Archive/2026-07-04-golden-test-ci/design/design) · [tasks](Design%20log/Archive/2026-07-04-golden-test-ci/tasks/tasks) · [specs](Design%20log/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

[Overview](#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

[Overview](#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

[Overview](#C4-Builder)

- [ci-validation](Design%20log/Archive/2026-07-04-golden-test-ci/specs/ci-validation/ci-validation)
- [regression-testing](Design%20log/Archive/2026-07-04-golden-test-ci/specs/regression-testing/regression-testing)

## ci-validation

[Overview](#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

[Overview](#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
' Shared diagram theme of the site. Colours are the standard C4-PlantUML ones, as on the
' landing page; external systems are darker than the standard grey so white text reads well.
' Included after the C4 stdlib include: !include styles.iuml (from the src root),
' !include ../styles.iuml (from a page folder).

skinparam shadowing false
skinparam roundCorner 10

UpdateElementStyle("external_system", $bgColor="#5c6977", $borderColor="#46535f")
```