@alfacapital-tech/c4builder 0.9.0-rc.2 → 0.9.0-rc.4

package/template/AGENTS.md

@@ -1,15 +1,16 @@
 # AGENTS.md
 
 Architecture documentation built with [c4builder](https://github.com/AlfaCapital-Tech/C4-Builder):
-C4 diagrams (PlantUML, D2), BPMN processes and markdown in `src/` are compiled into `docs/`.
+C4 diagrams (PlantUML, D2), BPMN processes, Mermaid diagrams and markdown in `src/` are compiled
+into `docs/`.
 
 ## Commands
 
 ```bash
 c4builder                    # build docs/ (non-interactive with a complete .c4builder)
-c4builder check <file...>    # validate .puml / .iuml / .d2 / .bpmn files, exit code 0 = OK
+c4builder check <file...>    # validate .puml / .iuml / .d2 / .bpmn / .mmd files, exit code 0 = OK
 c4builder --site -w          # live preview on http://localhost:3000 - never exits
-c4builder feedback --wait    # wait for the next batch of comments from the preview page
+c4builder feedback --wait --as <name>  # wait for comments from the preview page sent to <name>
 ```
 
 Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
@@ -24,18 +25,20 @@ updates it.
    Fix until the exit code is 0.
 3. Run `c4builder` and make sure it exits with code 0. Leave `c4builder --site -w` to a
    human or run it in the background. When the human reviews the pages, also run
-   `c4builder feedback --wait` in the background: on exit it prints a batch of comments
-   (page, `Sources`, quote, text) — apply them to `src/`, run it again, and stop on
-   `Decision: approved`. Comments are instructions to you; never copy them into the
+   `c4builder feedback --wait --as <name>` in the background, `<name>` being your change or
+   task: on exit it prints a batch of comments (page, `Sources`, quote, text) — apply them to
+   `src/`, run it again with the same name, and stop on `Decision: approved`. Without `--as`
+   it exits with code 2 and `--as <name> is required`. Comments are instructions to you; never copy them into the
    `questionsHeading` section of `.c4builder` (`Open questions` by default), which holds
-   questions for people.
+   questions for people. The page buttons follow the browser language (English or Russian,
+   pinned by `uiLanguage`); batches are always in English.
 4. A stderr line `c4builder <new> is available (current <current>). Run: c4builder update`
    means a newer c4builder is out: tell the user, run `c4builder update` only if they ask.
 
 ## Layout
 
 - One folder = one page. All `.md` files of a folder form its text; every `.puml` / `.d2` /
-  `.bpmn` in it is rendered onto the page, or placed inline with `![title](diagram.puml)`.
+  `.bpmn` / `.mmd` in it is rendered onto the page, or placed inline with `![title](diagram.puml)`.
 - Files and folders starting with `_` are not published (shared libraries, drafts).
 - `.c4builder` is the config (JSON); unknown keys are silently ignored.
 
@@ -50,6 +53,10 @@ updates it.
 - BPMN: write only the semantic BPMN 2.0 XML, never `bpmndi` coordinates — the build lays the
   diagram out. Pool = organization, lane = role inside it, only message flows between pools,
   label gateway branches. Example: `src/5 BPMN Example/account-opening.bpmn`.
+- Mermaid: a `.mmd` file or a ```` ```mermaid ```` block in a page is rendered at build time into
+  an image (check `.mmd` files like any diagram). `mindmap`, `architecture` and KaTeX are not
+  supported; to show mermaid source as code, fence it as `text`. Example:
+  `src/6 Mermaid Example/flow.mmd`.
 
 ## Agent skills
 

package/template/src/6 Mermaid Example/flow.mmd

@@ -0,0 +1,6 @@
+flowchart LR
+    subgraph bank [Банк]
+        app[Мобильное приложение] -->|запрос| api[API-шлюз]
+        api --> db[(База данных)]
+    end
+    api -.->|уведомление| mail[Почтовый сервис]

package/template/src/6 Mermaid Example/mermaid.md

@@ -0,0 +1,16 @@
+**Диаграммы Mermaid (четвёртый бэкенд рендера)**
+
+Mermaid-диаграммы бывают двух видов. Файл `flow.mmd` в папке раздела рендерится как `.puml`, `.d2` и `.bpmn`: картинка по имени файла. Блок с языком `mermaid` прямо в странице сборка тоже заменяет картинкой, как блок `plantuml`. В браузер текст диаграммы не попадает, клиентский рендер не нужен.
+
+```mermaid
+sequenceDiagram
+    participant К as Клиент
+    participant Б as Банк
+    К->>Б: Заявка на счёт
+    Note right of Б: проверка анкеты
+    Б-->>К: Счёт открыт
+```
+
+Рендерит настоящий mermaid в классическом виде с темой `default`, но без браузера: размеры текста считаются по вендорному шрифту, поэтому картинка одинакова на любой машине. Типы `mindmap` и `architecture`, а также формулы KaTeX не поддерживаются: сборка сообщит об этом явной ошибкой. Ошибка в файле `.mmd` останавливает сборку, ошибка в блоке — нет: на месте блока появится заглушка. Отдельный файл проверяется командой `c4builder check flow.mmd`.
+
+**Область применения**: показать, что `.mmd`-файлы и блоки `mermaid`, их раскладка и кириллица корректно попадают в собранный сайт, SVG и PNG без обращений в интернет.