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

package/README.MD

@@ -60,8 +60,9 @@ c4builder check src/context.puml   # exit code 0 or 1, "✗ file: line N: messag
 c4builder --site -w                # rebuilds and reloads the browser on every save
 ```
 
-For agents: `npx skills add AlfaCapital-Tech/C4-Builder/skills` installs the skills, and
-`"generateLLMS": true` adds `llms.txt` / `llms-full.txt` (diagram sources included) to the site.
+For agents: `c4builder skills` installs the agent skills of the installed version into the project
+(`c4builder --new` does it for a new one), and `"generateLLMS": true` adds `llms.txt` /
+`llms-full.txt` (diagram sources included) to the site.
 
 Or with Docker (Node, JRE, PlantUML, fonts and D2 included):
 

package/dist/cli/commands/new.js

@@ -7,6 +7,7 @@ import Configstore from 'configstore';
 import { readFile, writeFile, makeDirectory } from "../../util/utils.js";
 import { defaultConfig } from "../../config/defaults.js";
 import { TEMPLATE_DIR } from "../../util/paths.js";
+import cmdSkills from "./skills.js";
 // Общая проверка имени проекта: возвращает текст ошибки или null (валидно).
 // Интерактив показывает её и переспрашивает; --yes падает с ней (exit≠0), без ре-промпта.
 const validateProjectName = (name) => {
@@ -55,6 +56,8 @@ export default async (opts = {}) => {
     }
     await makeDirectory(projectName);
     await generateTemplate(TEMPLATE_DIR, projectName);
+    // Скиллы рядом с src/, как AGENTS.md: сборка их не видит (change skills-install, D6).
+    cmdSkills(path.join(process.cwd(), projectName));
     const conf = new Configstore(path.join(process.cwd(), projectName).split(path.sep).splice(1).join('_'), {}, { configPath: path.join(process.cwd(), projectName, '.c4builder') });
     // --yes: полный конфиг из единого defaultConfig → последующий c4builder собирает
     // без wizard'а. Интерактив пишет только projectName (первая сборка ведёт через wizard).

package/dist/cli/commands/site.js

@@ -100,7 +100,7 @@ pages = () => new Map()) => {
     const distFolder = path.resolve(currentConfiguration.DIST_FOLDER);
     const liveReloadEnabled = !!(program.watch && reloadEmitter);
     const agent = { ...(program.agent ?? { on: false, name: '', explicit: false }) };
-    // Кеш index.html — отдаём его из памяти, если на диске его временно нет
+    // Кеш корневого index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
     let sweeper;
@@ -421,6 +421,9 @@ pages = () => new Map()) => {
             }
             let filePath;
             const isIndex = urlPath.endsWith('/');
+            // docsify — один корневой index.html с hash-роутингом. Фолбэк окна ребилда только
+            // для корня: иначе любой несуществующий `…/` отвечал бы 200 главной, а не 404.
+            const isRoot = urlPath === '/';
             if (isIndex) {
                 filePath = path.join(distFolder, urlPath, 'index.html');
             }
@@ -436,14 +439,14 @@ pages = () => new Map()) => {
             fs.readFile(resolved, 'utf8', (err, data) => {
                 if (err) {
                     // ENOENT в окне ребилда (emptyDir → запись) — отдаём последний известный index.html.
-                    if (isIndex && lastIndexHtml) {
+                    if (isRoot && lastIndexHtml) {
                         res.set('Cache-Control', 'no-store').type('html').send(lastIndexHtml);
                         return;
                     }
                     return next();
                 }
                 const page = inject(data);
-                if (isIndex)
+                if (isRoot)
                     lastIndexHtml = page;
                 res.set('Cache-Control', 'no-store').type('html').send(page);
             });
@@ -453,7 +456,11 @@ pages = () => new Map()) => {
     // статику через app.use (тот же эффект: fallthrough-обработчик всех GET).
     app.use(express.static(distFolder));
     return new Promise((resolve, reject) => {
-        const server = app.listen(port, '127.0.0.1', () => {
+        // Express 5 зовёт колбэк listen и с ошибкой (занятый порт) — её разбирает
+        // server.on('error') ниже, а «serving» печатаем только после настоящего listen.
+        const server = app.listen(port, '127.0.0.1', (err) => {
+            if (err)
+                return;
             const url = `http://localhost:${port}`;
             console.log('serving your docsify site');
             console.log(`go to ${chalk.green(url)}`);

package/dist/cli/commands/skills.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { detectAgent } from "../agent.js";
+import { compareVersions, disabled } from "../update.js";
+import { PACKAGE_ROOT, packageJson as pkg } from "../../util/paths.js";
+// Скиллы агентов (change skills-install): входят в пакет, поэтому ставятся офлайн и той же версии,
+// что и CLI. По основному скиллу судим обо всём наборе — ставятся все сразу (D3).
+const SKILLS_DIR = path.join(PACKAGE_ROOT, 'skills');
+const MAIN = 'c4builder';
+const RUN = 'c4builder skills';
+// Отметка версии из frontmatter `<root>/c4builder/SKILL.md` регуляркой, без YAML-парсера (D4):
+// undefined — скилла нет, '' — скилл без отметки (поставлен `npx skills add` или руками).
+const stampIn = (root) => {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(root, MAIN, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const front = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '';
+    return front.match(/^\s+generatedBy:\s*["']?([^"'\s]+)/m)?.[1] ?? '';
+};
+// Копия новее CLI не устаревшая: о старом CLI скажет уведомление о новой версии (D4).
+const outdated = (stamp) => !stamp || compareVersions(stamp, pkg.version) < 0;
+const personalRoot = (dir) => path.join(os.homedir(), dir, 'skills');
+const overrides = (dir, stamp) => `~/${dir}/skills/${MAIN} (${stamp || 'no version'}) overrides project skills. Ask the user to remove it`;
+// `c4builder skills` и `--new` (D2, D6): каталог каждого скилла пакета заменяется целиком — так уходят
+// файлы прошлых версий, а чужие скиллы рядом не трогаются. `.claude` — только под Claude Code или если
+// он уже есть: Claude Code не читает `.agents`, а создавать `.claude/` в чужом проекте незачем.
+export default (root = process.cwd()) => {
+    const names = fs
+        .readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    const dirs = ['.agents'];
+    if (process.env.CLAUDECODE || fs.existsSync(path.join(root, '.claude')))
+        dirs.push('.claude');
+    for (const dir of dirs) {
+        for (const name of names) {
+            const target = path.join(root, dir, 'skills', name);
+            fs.rmSync(target, { recursive: true, force: true });
+            fs.cpSync(path.join(SKILLS_DIR, name), target, { recursive: true });
+            const file = path.join(target, 'SKILL.md');
+            const text = fs.readFileSync(file, 'utf8');
+            fs.writeFileSync(file, text.replace(/^description:.*$/m, `$&\nmetadata:\n  generatedBy: "${pkg.version}"`));
+            console.log(`installed ${path.relative(process.cwd(), target)}`);
+        }
+        // Личную копию не трогаем: её поставил пользователь, удалять — ему (D3).
+        const personal = stampIn(personalRoot(dir));
+        if (personal !== undefined && outdated(personal))
+            console.error(overrides(dir, personal));
+    }
+};
+// Строка о скиллах при старте сборки и `site` под агентом (D3–D5), undefined — молчим. Агент — только
+// по окружению: флаги --agent/--no-agent управляют замечаниями со страницы, а не этим.
+export const skillsNotice = (cwd = process.cwd()) => {
+    const agent = detectAgent(process.env, {});
+    if (!agent.on || disabled())
+        return undefined;
+    const dir = agent.name === 'claude-code' ? '.claude' : '.agents';
+    // Личная копия побеждает проектную при одинаковом имени (так выбирает Claude Code).
+    const personal = stampIn(personalRoot(dir));
+    if (personal !== undefined)
+        return outdated(personal) ? `${overrides(dir, personal)}, then run: ${RUN}` : undefined;
+    // Проектная — ближайшая от cwd вверх до корня git-репозитория: агента обычно запускают в корне
+    // репозитория, а сборку — в подкаталоге документации, и он видит скиллы обоих уровней.
+    let stamp;
+    for (let d = path.resolve(cwd); stamp === undefined; d = path.dirname(d)) {
+        stamp = stampIn(path.join(d, dir, 'skills'));
+        if (fs.existsSync(path.join(d, '.git')) || path.dirname(d) === d)
+            break;
+    }
+    if (stamp === undefined)
+        return `c4builder agent skills are not installed here. Ask the user, then run: ${RUN}`;
+    if (!outdated(stamp))
+        return undefined;
+    return `c4builder agent skills here are from ${stamp || 'an unknown version'} (current ${pkg.version}). Ask the user, then run: ${RUN}`;
+};

package/dist/cli/dispatch.js

@@ -10,6 +10,7 @@ import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
 import cmdFeedback from "./commands/feedback.js";
+import cmdSkills, { skillsNotice } from "./commands/skills.js";
 import { detectAgent } from "./agent.js";
 import { cmdUpdate, pendingUpdate, startUpdateCheck } from "./update.js";
 import cmdCollect from "./wizard/collect.js";
@@ -30,7 +31,25 @@ import { packageJson as pkg } from "../util/paths.js";
 import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 // Позиционные подкоманды: allowExcessArguments пропускает любые, список — единственный фильтр.
-const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update', 'feedback'];
+// Commander о них не знает — аргументы и описания здесь же, для блока команд в --help.
+const COMMANDS = {
+    check: ['<files...>', 'check diagrams without a build, exit code 0 or 1'],
+    jre: ['info|install', 'which Java will be used | download a JRE in advance'],
+    site: ['', 'build and serve the site locally (same as --site)'],
+    new: ['', 'create a project from the template (same as --new)'],
+    config: ['', 'setup wizard with the current values (same as --config)'],
+    update: ['', 'update a global npm install to the newest version'],
+    feedback: ['', 'wait for page feedback from site -w (--wait --as <name>)'],
+    skills: ['', 'install or update the agent skills in the current folder']
+};
+const commandsHelp = () => {
+    const rows = Object.entries(COMMANDS).map(([name, [args, about]]) => [
+        `${name} ${args}`.trim(),
+        about
+    ]);
+    const width = Math.max(...rows.map(([usage]) => usage.length));
+    return `\nCommands:\n${rows.map(([usage, about]) => `  ${usage.padEnd(width)}  ${about}`).join('\n')}`;
+};
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -112,6 +131,8 @@ function getOptions(c) {
 }
 export default async () => {
     program
+        .name('c4builder')
+        .usage('[command] [options]')
         .version(pkg.version)
         .option('--new', 'create a new project from template')
         .option('--name <name>', 'project name for --new (skips the name prompt)')
@@ -137,14 +158,15 @@ export default async () => {
         return Number(v);
     })
         .allowExcessArguments() // позиционные аргументы подкоманд `jre <action>` и `check <file...>`
+        .addHelpText('after', commandsHelp())
         .parse(process.argv);
     const opts = program.opts();
     const [cmd, ...cmdArgs] = program.args;
     // allowExcessArguments глотает любой позиционный аргумент — без этой проверки
     // опечатка (`c4builder nwe`) молча превращалась бы в сборку.
-    if (cmd !== undefined && !COMMANDS.includes(cmd)) {
+    if (cmd !== undefined && !Object.hasOwn(COMMANDS, cmd)) {
         console.error(chalk.red(`unknown command: ${cmd}`));
-        console.error(`available commands: ${COMMANDS.join(', ')} (see c4builder --help for options)`);
+        console.error(`available commands: ${Object.keys(COMMANDS).join(', ')} (see c4builder --help for options)`);
         process.exit(1);
     }
     // --version/--help уже вышли в parse. Уведомление — по кэшу прошлой проверки, до её
@@ -167,6 +189,9 @@ export default async () => {
     // Замечания со страницы `site -w` — тоже до Configstore: команду запускают в любом каталоге.
     if (cmd === 'feedback')
         return cmdFeedback(path.join(process.cwd(), opts.configFile ?? '.c4builder'), opts);
+    // Установка скиллов — до Configstore: ставит их и в каталог без проекта.
+    if (cmd === 'skills')
+        return cmdSkills();
     // `site`/`new`/`config` — позиционные синонимы одноимённых флагов: эту форму печатают
     // подсказки CLI и учат README, шаблон и скиллы.
     if (cmd)
@@ -180,6 +205,11 @@ export default async () => {
         console.error(chalk.red(`no .c4builder in ${process.cwd()} — run inside a project or create one with c4builder new`));
         process.exit(1);
     }
+    // Без терминала мастеру неоткуда взять ответы: inquirer падал со стектрейсом и кодом 0.
+    if (!opts.new && !process.stdin.isTTY && !fs.existsSync(configPath)) {
+        console.error(chalk.red(`no ${opts.configFile ?? '.c4builder'} in ${process.cwd()} — run c4builder --new, or c4builder --config in a terminal`));
+        process.exit(1);
+    }
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.
@@ -187,7 +217,15 @@ export default async () => {
     if (!opts.new) {
         const projectKey = process.cwd().split(path.sep).splice(1).join('_');
         lockPath = `${configPath}.lock`;
-        conf = new Configstore(projectKey, {}, { configPath });
+        try {
+            // По умолчанию Configstore молча затирает битый JSON пустым конфигом — настройки
+            // терялись, а сборка уходила в мастер. --reset стирает конфиг и так.
+            conf = new Configstore(projectKey, {}, { configPath, clearInvalidConfig: !!opts.reset });
+        }
+        catch (e) {
+            console.error(chalk.red(`.c4builder error — cannot read ${configPath}: ${e.message}`));
+            process.exit(1);
+        }
         cacheConf = new Configstore(`${projectKey}_cache`, {}, { configPath: `${configPath}.cache` });
         // Миграция: чексуммы раньше жили в .c4builder, переносим их в .c4builder.cache,
         // чтобы рабочий конфиг перестал «дёргаться» в git при каждой сборке.
@@ -247,6 +285,10 @@ export default async () => {
     }
     await cmdCollect(currentConfig, conf, opts);
     if (!opts.config) {
+        // При старте, а не при выходе, как уведомление о версии: `site -w` живёт до остановки.
+        const skills = skillsNotice();
+        if (skills)
+            process.stderr.write(`${skills}\n`);
         let isBuilding = false;
         let attemptedWatchBuild = false;
         // Опции сборки после визарда: строгий разбор итогового конфига. Штатно валиден
@@ -359,8 +401,15 @@ export default async () => {
             }
         }
         isBuilding = false;
-        if (opts.site)
-            return await cmdSite(options, { ...opts, agent: detectAgent(process.env, opts) }, reloadEmitter, () => pages);
+        if (opts.site) {
+            try {
+                return await cmdSite(options, { ...opts, agent: detectAgent(process.env, opts) }, reloadEmitter, () => pages);
+            }
+            catch {
+                // Ошибку запуска сервера (занятый порт) cmdSite уже напечатал — остаётся код выхода.
+                process.exit(1);
+            }
+        }
         if (options.GENERATE_WEBSITE && !opts.watch) {
             console.log(chalk.gray('\nto view the generated website run'));
             console.log(`> c4builder site`);

package/dist/cli/update.js

@@ -19,7 +19,7 @@ const npmSync = (args, options) => {
 };
 // CI ставят GitLab CI, GitHub Actions и большинство CI; C4BUILDER_DOCKER — наш Dockerfile;
 // NO_UPDATE_NOTIFIER — общая конвенция с пакетом update-notifier.
-const disabled = () => !!(process.env.CI || process.env.NO_UPDATE_NOTIFIER || process.env.C4BUILDER_DOCKER);
+export const disabled = () => !!(process.env.CI || process.env.NO_UPDATE_NOTIFIER || process.env.C4BUILDER_DOCKER);
 const cacheFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'c4builder', 'dist-tags.json');
 // Порядок semver без зависимости semver: numeric-коллатор сравнивает цифровые серии численно
 // (0.10.0 > 0.9.0, rc.10 > rc.2); стабильная версия старше пререлиза того же ядра.

package/dist/core/build.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import path from 'node:path';
 import fsextra from 'fs-extra';
-import { makeDirectory, writeFile, writeOnSameLine } from "../util/utils.js";
+import { makeDirectory, writeFile, writeProgress } from "../util/utils.js";
 // clearD2FileCache: сброс кеша графа D2-импортов на границах сборки (сам webworker
 // D2 гасит CLI после одиночной сборки — в watch-режиме он переживает ребилды).
 import { clearD2FileCache } from "./render/d2renderer.js";
@@ -57,16 +57,12 @@ const build = async (options, cacheConf, plugins = []) => {
         }
         if (options.GENERATE_LOCAL_IMAGES) {
             console.log(chalk.blue('generating images'));
-            await generateImages(tree, options, (count, total) => {
-                writeOnSameLine(`processed ${count}/${total} images`);
-            }, cacheConf, bkFolderName);
+            await generateImages(tree, options, (count, total) => writeProgress(count, total, 'images'), cacheConf, bkFolderName);
             console.log('');
         }
         if (options.GENERATE_MD) {
             console.log(chalk.blue('generating markdown files'));
-            await generateMD(tree, options, (count, total) => {
-                writeOnSameLine(`processed ${count}/${total} files`);
-            });
+            await generateMD(tree, options, (count, total) => writeProgress(count, total, 'files'));
             console.log('');
         }
         if (options.GENERATE_WEBSITE) {

package/dist/index.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
 //entry point
 import cli from "./cli/dispatch.js";
-cli();
+// Закрытый промпт (Ctrl+C или EOF без терминала) — отмена, а не сбой: одна строка вместо
+// стектрейса inquirer. Код выставляем сами: на EOF процесс уже выходил с кодом 0, и CI
+// принимал несобранный сайт за успех.
+cli().catch((e) => {
+    if (!(e instanceof Error && e.name === 'ExitPromptError'))
+        throw e;
+    console.error(`aborted: the prompt was closed${process.stdin.isTTY ? '' : ' (no terminal for the wizard)'}`);
+    process.exit(1);
+});

package/dist/util/utils.js

@@ -9,8 +9,14 @@ const makeDirectory = async (path) => {
 // Кодировка не передаётся ни одним вызовом → всегда Buffer (потребители зовут .toString()).
 const readFile = (path) => fs.promises.readFile(path);
 const writeFile = (path, data) => fs.promises.writeFile(path, data);
-const writeOnSameLine = async (message) => {
-    process.stdout.write(`${message}\r`);
+// Вне терминала (лог фонового `--site -w`, CI) `\r` не перетирает строку, а склеивает
+// все обновления в одну гигантскую — там печатаем только итог фазы. Перевод строки
+// после прогресса ставит вызывающий.
+const writeProgress = (count, total, unit) => {
+    if (process.stdout.isTTY)
+        process.stdout.write(`processed ${count}/${total} ${unit}\r`);
+    else if (count === total)
+        process.stdout.write(`processed ${total} ${unit}`);
 };
 const encodeURIPath = (path) => {
     path = path.split('\\').join('/');
@@ -110,4 +116,4 @@ const VENDORED_JAR = {
     version: '1.2026.8',
     jar: 'plantuml-1.2026.8.jar'
 };
-export { makeDirectory, readFile, writeFile, encodeURIPath, writeOnSameLine, clearConsole, plantUmlServerUrl, VENDORED_JAR };
+export { makeDirectory, readFile, writeFile, encodeURIPath, writeProgress, clearConsole, plantUmlServerUrl, VENDORED_JAR };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.9.0",
+  "version": "0.10.0-rc.2",
   "description": "A CLI tool designed to compile a folder structure of markdowns and plant uml files into a site, single file markdown or a collection of markdowns with links",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
     "!template/docs",
     "!template/.c4builder",
     "vendor/",
+    "skills/",
     "README.MD",
     "license"
   ],

package/skills/c4builder/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: c4builder
+description: Work on a c4builder architecture-docs project - C4 model diagrams in PlantUML (C4-PlantUML stdlib) or D2, BPMN process diagrams, Mermaid diagrams, plus markdown, built into a docsify site or markdown files. Use when creating or editing .puml, .iuml, .d2, .bpmn, .mmd or .md files in a project that has a .c4builder config, when changing .c4builder settings or plugins (openspec, openapi), or when building, validating or previewing the docs. Teaches the edit, c4builder check, build loop and the C4-PlantUML conventions.
+---
+
+# c4builder
+
+c4builder compiles a folder tree of markdown and diagrams into documentation: a docsify
+site, a collection of markdown files with navigation and/or one complete markdown file.
+Installing or repairing the CLI itself is the `c4builder-setup` skill.
+
+A c4builder project is a folder with a `.c4builder` file (JSON config) next to the source
+folder (`rootFolder`, `src` by default).
+
+## Project layout
+
+```text
+.c4builder              config (JSON)            -> references/config.md
+.c4builder.cache        render checksums         (git-ignored)
+src/                    rootFolder: one folder = one page
+  context.md            page text
+  context.puml          diagram attached to the same page
+  styles.iuml           shared PlantUML styles, included by diagrams
+  _c4lib.d2             "_" prefix: never rendered or published, still includable
+  1 Internet Banking System/
+    system.md
+    system.puml
+    API Application/
+      container.md
+      container.puml
+docs/                   distFolder: generated, wiped on every build
+```
+
+How the source tree becomes pages:
+
+- Every folder is one page and one node in the navigation; the page title is the folder
+  name (the root page is `homepageName`). Siblings are sorted by name — prefix folders with
+  numbers (`1 …`, `2 …`) to order them.
+- All `.md` files of a folder are concatenated into its page.
+- Every `.puml` / `.d2` / `.bpmn` / `.mmd` in a folder is rendered and attached to the page (on top by
+  default, `diagramsOnTop`), unless the markdown places it explicitly with
+  `![name](container.puml)` — then it appears exactly there.
+- Files and folders starting with `_` are skipped (use it for shared libraries and drafts);
+  `CLAUDE.md` is skipped too. Other files (images, `.iuml`) are copied next to the page —
+  keep their names unique across the project.
+- `foo.puml`, `foo.d2`, `foo.bpmn` and `foo.mmd` in one folder render to the same image name → build error.
+- Never edit `docs/` (or whatever `distFolder` is): every build regenerates it.
+
+## The loop: edit → check → build
+
+1. **Edit** markdown and diagrams under `src/`.
+2. **Check every diagram you changed** — fast, no project build, writes nothing:
+
+   ```bash
+   c4builder check src/context.puml "src/1 Internet Banking System/system.puml"
+   ```
+
+   Exit code 0 means every file compiles. Otherwise each broken file is reported as
+   `✗ <file>: line <N>: <message>` (PlantUML lines count from the top of the file). Errors
+   in a `.iuml` carry no line number; D2 errors end with `<file>:<line>:<col>: <message>`;
+   BPMN problems are `✗ <file>: <element id> [<rule>] <description>`, one line each;
+   mermaid errors are `✗ <file>: line <N>: <message>`.
+   Fix and re-run until the exit code is 0. A changed `.iuml` is checked directly too: a
+   styles file calling C4 macros (`UpdateElementStyle`) is checked with the C4 stdlib
+   included. Same engines as the build (bundled PlantUML jar, bundled D2, BPMN pipeline, mermaid), no
+   `.c4builder` needed.
+3. **Build** the whole project:
+
+   ```bash
+   c4builder
+   ```
+
+   With a complete `.c4builder` (written by `c4builder --new --name <name> -y` or by the
+   first interactive run) this is a one-off, non-interactive build. A missing or partial
+   config needs the interactive wizard; without a terminal the run stops with exit code 1.
+   Do not drive the wizard: ask the user or write the full config (references/config.md). A diagram that fails here aborts the build with a long
+   Java stack trace and keeps the previous output in `docs_bk/`; run `c4builder check` on
+   the changed files to get the short message.
+4. **Look at the result** in `docs/`: `docs/<folder>/README.md` (markdown collection),
+   `docs/index.html` + `docs/<folder>/<folder>.md` (site), `docs/<folder>/<diagram>.svg`.
+5. **Live preview for a human:** `c4builder --site -w` builds, serves on
+   `http://localhost:3000` (`webPort`, or `-p <n>`), rebuilds on save and reloads the
+   browser; `-o` opens it. It never exits — start it in the background or leave it to the
+   user. `c4builder site` builds and serves without watching (also never exits). In `-w` a
+   human can select text on a page and add a question: it lands in the source `.md` under the
+   `questionsHeading` section (`Open questions` by default) — read it there, not in `docs/`.
+
+## Feedback from the page
+
+When the user wants to look at the pages and tell you what to fix, use the `c4builder-review`
+skill (`/c4builder-review [change-id|page]`): it checks the server, gives the link to the page and
+runs the batch loop.
+
+In short: under an agent (`CLAUDECODE`, `CODEX_THREAD_ID`, `GEMINI_CLI`, `OPENCODE`, `COPILOT_CLI`,
+`AI_AGENT`, or `--agent`) `c4builder --site -w` adds a **Feedback** button to text selected on a
+page. The comments do not go into the files: `c4builder feedback --wait --as <name>`, run in the
+background with your change or task as `<name>`, exits with one batch on stdout. Apply it to the
+sources, run the command again with the same name and stop on `Decision: approved`.
+
+## Writing C4 diagrams (PlantUML)
+
+```plantuml
+@startuml
+!include <C4/C4_Container>
+!include ../styles.iuml
+
+Person(user, "Customer", "Uses the web app")
+System_Boundary(shop, "Shop") {
+    Container(web, "Web App", "TypeScript", "Catalog and checkout")
+    ContainerDb(db, "Database", "PostgreSQL", "Orders")
+}
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, db, "Reads/writes", "SQL")
+@enduml
+```
+
+- Include C4 from the PlantUML stdlib: `!include <C4/C4_Context>`, `<C4/C4_Container>`,
+  `<C4/C4_Component>`, `<C4/C4_Dynamic>`, `<C4/C4_Deployment>`. It is bundled in the jar —
+  builds work offline. Never `!include https://…` (network on every build, breaks CI).
+- Shared look lives in one `.iuml` (the template's `src/styles.iuml`), included **after**
+  the C4 include by a path relative to the diagram: `!include styles.iuml` from `src/`,
+  `!include ../styles.iuml` one level down.
+- One diagram per file, `@startuml` … `@enduml`, file name = image name.
+- Non-Latin text (Cyrillic etc.) works: sources are UTF-8, the bundled font covers it.
+
+Details — sequence/class diagrams, D2, fonts, PNG output: read
+[references/diagrams.md](references/diagrams.md) when writing anything beyond a plain
+C4-PlantUML diagram.
+
+## Business processes (BPMN)
+
+A `.bpmn` file is BPMN 2.0 XML with **only the semantic model** — no `bpmndi` coordinates:
+the build validates the model and lays it out with horizontal pools and lanes. Read
+[references/bpmn.md](references/bpmn.md) before creating or editing any `.bpmn` file: source
+format, pool/lane conventions and how to fix every `c4builder check` message.
+
+## Mermaid
+
+`.mmd` files and ```` ```mermaid ```` blocks in pages and OpenSpec artifacts are rendered at
+build time into images (real mermaid, no browser). Use them for flows, sequences, states and
+ER inside the docs; keep the C4 model in PlantUML. Read
+[references/mermaid.md](references/mermaid.md) before writing mermaid: supported types,
+fixed config keys and the `c4builder check` loop.
+
+## Config and plugins
+
+- Read [references/config.md](references/config.md) before editing `.c4builder`: unknown
+  keys are **silently dropped**, so a typo does nothing. `c4builder --list` prints the
+  current config.
+- Read [references/plugins.md](references/plugins.md) when the project has or needs
+  `plugins` — `openspec` (OpenSpec store as a site section) or `openapi` (swagger-ui pages).
+
+## Reading an existing architecture
+
+With `generateLLMS: true` the built site has `llms.txt` (every page in sidebar order, links
+to its `.md`) and `llms-full.txt` (all pages in one file, diagrams inlined as PlantUML/D2/BPMN/Mermaid
+source, shared local includes once in an appendix). To answer questions about a documented
+system, read `llms-full.txt` from the site or `distFolder` instead of crawling pages or
+images: the C4 source (`Person`, `System`, `Rel`) is the model itself.
+
+## New version notice
+
+When c4builder output ends with a stderr line
+
+```text
+c4builder <new> is available (current <current>). Run: c4builder update
+```
+
+a newer c4builder is published. Tell the user. Run `c4builder update` only when the user asks
+for it: it reinstalls the global CLI. The notice changes neither stdout nor the exit code.
+
+## Skills notice
+
+When a build or `c4builder site` run by an agent starts with one of these stderr lines
+
+```text
+c4builder agent skills are not installed here. Ask the user, then run: c4builder skills
+c4builder agent skills here are from <stamp> (current <version>). Ask the user, then run: c4builder skills
+~/.claude/skills/c4builder (<stamp|no version>) overrides project skills. Ask the user to remove it, then run: c4builder skills
+```
+
+the c4builder skills you work with are missing, older than the CLI, or shadowed by a stale personal
+copy (`~/.agents/skills/c4builder` for agents other than Claude Code). Tell the user. Run
+`c4builder skills` only when the user agrees: it writes the skills of the installed CLI into
+`.agents/skills/` of the current folder (and `.claude/skills/` under Claude Code), replacing the
+c4builder skills there. Remove a personal copy only when the user agrees. The notice changes
+neither stdout nor the exit code.
+
+## Common mistakes
+
+- Editing generated files in `docs/` instead of `src/`.
+- Remote `!include` URLs instead of `<C4/...>` stdlib includes.
+- Running `c4builder --site -w` or `c4builder feedback --wait --as <name>` in the foreground — the
+  agent hangs.
+- Forgetting `c4builder check` and reading a Java stack trace from the full build instead.
+- A page "missing" from the output because its file or folder starts with `_`.
+- `generateLocalImages: false` in a project with `.d2`, `.bpmn` or `.mmd` files — they have no online
+  renderer, the build stops with an error.
+- Writing `bpmndi` coordinates into a `.bpmn` — they are ignored; the layout is always automatic.