@alfacapital-tech/c4builder 0.9.0-rc.4 → 0.10.0-rc.1

package/README.MD

@@ -31,6 +31,9 @@ than a hundred diagrams, so we continue it as a maintained fork, adapted to work
   and lays it out with horizontal pools and lanes.
 - **Mermaid** `.mmd` files and ```` ```mermaid ```` blocks are rendered at build time by real mermaid,
   without a browser: images in every output instead of client-side rendering.
+- **Review from the page.** In `c4builder --site -w` a selection becomes a question in the source
+  `.md` or feedback for the agent; `c4builder feedback --wait --as <name>` hands the batch to the
+  agent, and the page reloads with its edits.
 - **Maintained.** TypeScript, golden rendering snapshots, CI on every pull request, releases to
   npm and GHCR. The PDF output of the original was removed.
 
@@ -57,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/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,7 @@ 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'];
+const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update', 'feedback', 'skills'];
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -167,6 +168,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)
@@ -247,6 +251,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;
         // Опции сборки после визарда: строгий разбор итогового конфига. Штатно валиден

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.9.0-rc.4",
+  "version": "0.10.0-rc.1",
   "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 starts an interactive wizard — do not drive it, 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.

package/skills/c4builder/references/bpmn.md

@@ -0,0 +1,138 @@
+# BPMN reference
+
+`.bpmn` files are business processes in BPMN 2.0 notation. Write **only the semantic model**;
+c4builder validates it, lays it out (horizontal pools and lanes, flow left to right) and
+renders it in the standard bpmn.io notation — offline and deterministically.
+
+## Source format
+
+- Standard BPMN 2.0 XML, namespace `http://www.omg.org/spec/BPMN/20100524/MODEL`.
+- **No coordinates.** Do not write a `bpmndi:BPMNDiagram` section: it is ignored anyway, the
+  build always computes the layout. There is no way to hand-tune positions.
+- `incoming` / `outgoing` elements are optional — connections are taken from
+  `sourceRef` / `targetRef` of the flows.
+- `isExecutable="false"`: this is documentation, not an executable process; no Camunda or
+  Flowable extensions are needed.
+- Give elements readable ids with a type prefix (`Task_CheckDocuments`, `Gateway_Decision`,
+  `Flow_Approved`): every error message points to an id.
+
+Minimal example — a pool with two lanes, an external "black-box" pool, a gateway with
+labelled branches, a boundary timer and message flows:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  id="Definitions_Order" targetNamespace="https://example.com/bpmn/order">
+  <bpmn:collaboration id="Collaboration_Order">
+    <bpmn:participant id="Pool_Shop" name="Shop" processRef="Process_Order" />
+    <bpmn:participant id="Pool_Bank" name="Payment bank" />
+    <bpmn:messageFlow id="Message_Charge" name="Charge request"
+                      sourceRef="Task_Charge" targetRef="Pool_Bank" />
+    <bpmn:messageFlow id="Message_Result" name="Payment result"
+                      sourceRef="Pool_Bank" targetRef="Task_AwaitPayment" />
+  </bpmn:collaboration>
+  <bpmn:process id="Process_Order" name="Order" isExecutable="false">
+    <bpmn:laneSet id="LaneSet_Shop">
+      <bpmn:lane id="Lane_Sales" name="Sales">
+        <bpmn:flowNodeRef>Start_Order</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_Charge</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Task_AwaitPayment</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>Gateway_Paid</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_Cancelled</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_Expired</bpmn:flowNodeRef>
+      </bpmn:lane>
+      <bpmn:lane id="Lane_Warehouse" name="Warehouse">
+        <bpmn:flowNodeRef>Task_Ship</bpmn:flowNodeRef>
+        <bpmn:flowNodeRef>End_Shipped</bpmn:flowNodeRef>
+      </bpmn:lane>
+    </bpmn:laneSet>
+    <bpmn:startEvent id="Start_Order" name="Order placed" />
+    <bpmn:sendTask id="Task_Charge" name="Request payment" />
+    <bpmn:receiveTask id="Task_AwaitPayment" name="Await payment" />
+    <bpmn:boundaryEvent id="Timer_PaymentTimeout" name="1 hour" attachedToRef="Task_AwaitPayment">
+      <bpmn:timerEventDefinition id="TimerDef_PaymentTimeout" />
+    </bpmn:boundaryEvent>
+    <bpmn:exclusiveGateway id="Gateway_Paid" name="Paid?" />
+    <bpmn:userTask id="Task_Ship" name="Ship order" />
+    <bpmn:endEvent id="End_Shipped" name="Order shipped" />
+    <bpmn:endEvent id="End_Cancelled" name="Order cancelled" />
+    <bpmn:endEvent id="End_Expired" name="Payment expired" />
+    <bpmn:sequenceFlow id="Flow_Start" sourceRef="Start_Order" targetRef="Task_Charge" />
+    <bpmn:sequenceFlow id="Flow_Charged" sourceRef="Task_Charge" targetRef="Task_AwaitPayment" />
+    <bpmn:sequenceFlow id="Flow_Answered" sourceRef="Task_AwaitPayment" targetRef="Gateway_Paid" />
+    <bpmn:sequenceFlow id="Flow_Yes" name="Yes" sourceRef="Gateway_Paid" targetRef="Task_Ship" />
+    <bpmn:sequenceFlow id="Flow_No" name="No" sourceRef="Gateway_Paid" targetRef="End_Cancelled" />
+    <bpmn:sequenceFlow id="Flow_Timeout" sourceRef="Timer_PaymentTimeout" targetRef="End_Expired" />
+    <bpmn:sequenceFlow id="Flow_Shipped" sourceRef="Task_Ship" targetRef="End_Shipped" />
+  </bpmn:process>
+</bpmn:definitions>
+```
+
+Elements that render: start/end/intermediate events with timer, message, error and other
+definitions, boundary events, `task`, `userTask`, `serviceTask`, `sendTask`, `receiveTask`,
+`manualTask`, `scriptTask`, `businessRuleTask`, exclusive/parallel/inclusive/event-based
+gateways, `subProcess`, `textAnnotation` with `association`, `dataObjectReference`.
+`complexGateway` is not supported by the layout engine.
+
+## Modelling conventions
+
+- **Pool = organization**, **lane = role or unit inside it.** An external party whose
+  internals you do not describe is a pool without `processRef` (a black box).
+- **Between pools — only message flows.** Sequence flows stay inside one pool; a message
+  flow may target a node or the black-box pool itself.
+- **Lanes:** when a process has lanes, list every flow node in exactly one lane
+  (`flowNodeRef`). Boundary events may be left out — they sit on their task.
+- **Label everything:** events, tasks, participants, lanes and diverging gateways need a
+  `name`. Label every outgoing flow of an exclusive/inclusive gateway (`Yes` / `No`).
+- **Exactly the start and end you mean:** a process needs a start and an end event; a node
+  without incoming or outgoing flows is an error, not an implicit start or end.
+- **Overview plus detail** instead of one huge diagram: above ~40 nodes the picture stops
+  being readable. Sub-processes are always drawn collapsed — describe their inside in a
+  separate `.bpmn` on its own page.
+
+## The loop
+
+```bash
+c4builder check "src/3 Processes/order.bpmn"
+```
+
+`check` runs the whole pipeline — parse, rules, layout and rendering — without a project.
+Exit code 0 means the diagram builds; warnings are printed but do not change the code. Each
+problem is one line:
+
+```text
+✗ src/3 Processes/order.bpmn: Task_Ship [no-disconnected] Element is not connected
+⚠ src/3 Processes/order.bpmn: Flow_No [c4builder/gateway-flow-labels] Outgoing flow of a diverging gateway has no label
+```
+
+Format: `<file>: <element id> [<rule>] <description>`. Fix the element with that id and run
+`check` again until the exit code is 0.
+
+| Message | Fix |
+|---|---|
+| `[no-disconnected]`, `[no-implicit-start]`, `[no-implicit-end]` | connect the node with sequence flows (check `sourceRef`/`targetRef` spelling) |
+| `[start-event-required]`, `[end-event-required]` | add the missing start or end event |
+| `[label-required]` | add a `name` |
+| `[c4builder/lane-membership]` | list the node in exactly one `flowNodeRef` of its process lanes |
+| `[c4builder/sequence-flow-in-pool]` | replace the sequence flow between pools with a `messageFlow` in the collaboration |
+| `[c4builder/message-flow-between-pools]` | a message flow inside one pool must be a sequence flow |
+| `[c4builder/gateway-flow-labels]` (warning) | name the gateway's outgoing flows |
+| `[no-inclusive-gateway]` (warning) | prefer exclusive or parallel gateways where possible |
+| `X: unresolved reference <Y>` | element `X` refers to an id `Y` that does not exist |
+| `invalid BPMN XML: …` | the file is not well-formed XML or not BPMN 2.0 |
+| `layout failed: …` / `layout lost N element(s): …` | the layout engine could not place the model: simplify it, split it into overview and detail, or move the listed elements |
+
+The rule set is fixed (bpmnlint `recommended` without `no-bpmndi`, plus the `c4builder/*`
+rules) and is the same in `check` and in the build — there is no project config for it.
+
+## Output and dependencies
+
+- The image is `<name>.svg` (or `.png` with `diagramFormat: png`) next to the page; place
+  it inline with `![title](name.bpmn)`. In `llms-full.txt` the source appears in an `xml`
+  block.
+- Text is measured with the bundled Nimbus Sans: the SVG is identical on every machine;
+  `useSystemFonts` does not affect BPMN.
+- The engine packages (`bpmn-js`, `bpmn-moddle`, `bpmnlint`, `bpmn-auto-layout`, `jsdom`)
+  are optional npm dependencies, loaded only when the project has a `.bpmn`. An install with
+  `--omit=optional` stops such a build with a hint to reinstall c4builder.
+- Like D2, BPMN has no online renderer: `generateLocalImages` must stay `true`.

package/skills/c4builder/references/config.md

@@ -0,0 +1,111 @@
+# `.c4builder` reference
+
+`.c4builder` is a JSON file in the project root (another path: `c4builder -c <path>`).
+`c4builder --list` prints the effective values, `c4builder --docs` explains the wizard
+questions, `c4builder --config` re-runs the wizard (interactive — prefer editing the JSON).
+
+Validation rules:
+
+- **Unknown keys are silently dropped.** A misspelled key (`generateWeb`) changes nothing —
+  compare every key with the tables below.
+- A wrong type (a string where a boolean is expected, a bad port) fails the build with a
+  message naming the key. `null` means "not set" → default.
+- The wizard asks for every key it knows that is **missing** from the file, so a
+  non-interactive build needs a complete config — like the one
+  `c4builder --new --name <name> -y` writes (below). `hasRun: true` (set after the first
+  successful build) makes invalid values fail the build instead of being asked again.
+
+## Sources and outputs
+
+| Key | Default | Meaning |
+|---|---|---|
+| `projectName` | — | documentation title; name of the complete markdown file |
+| `homepageName` | `Overview` | title of the root page |
+| `rootFolder` | `src` | source folder |
+| `distFolder` | `docs` | output folder — **wiped on every build** |
+| `generateMD` | `true` | markdown collection: `README.md` per folder |
+| `generateCompleteMD` | `false` | one `<projectName>.md` with everything |
+| `generateWEB` | `true` | docsify site (`index.html`, `<folder>.md` per folder) |
+| `generateLLMS` | `true` in new projects, off when absent | `llms.txt` (page index) and `llms-full.txt` (full text, diagrams as source) in the site root; needs `generateWEB` |
+| `excludeOtherFiles` | `false` | do not copy non-diagram, non-markdown files (images…) |
+
+## Page content
+
+| Key | Default | Meaning |
+|---|---|---|
+| `diagramsOnTop` | `true` | attached diagrams before the text (after a leading `#` title) |
+| `includeBreadcrumbs` | `true` | folder path under the title |
+| `includeNavigation` | `false` | markdown collection: links to parent and children |
+| `includeTableOfContents` | `true` | markdown collection: tree of all pages on every page |
+| `includeLinkToDiagram` | `false` | a link to the image instead of the image |
+| `embedDiagram` | `false` | images inlined as base64 data URIs |
+| `charset` | `UTF-8` | encoding of diagram sources |
+
+## Diagrams
+
+| Key | Default | Meaning |
+|---|---|---|
+| `generateLocalImages` | `true` | render locally (Java + bundled PlantUML, bundled D2). `false` = PlantUML images are links to `plantumlServerUrl`; a project with `.d2` files then fails |
+| `plantumlServerUrl` | `https://www.plantuml.com/plantuml` | server for `generateLocalImages: false` |
+| `diagramFormat` | `svg` | `svg` or `png` (PNG is rasterized from SVG; ditaa is always PNG) |
+| `d2Layout` | `dagre` | D2 layout engine: `dagre` or `elk` |
+| `useSystemFonts` | `false` | machine fonts instead of the bundled one — output differs per machine (`--system-fonts` for one run) |
+
+## Site (docsify)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `webPort` | `3000` | port of `c4builder --site` (`-p <n>` overrides) |
+| `questionsHeading` | `Open questions` | heading of the section in the source `.md` where `site -w` appends questions left on the page |
+| `uiLanguage` | `auto` | language of the `site -w` page interface: `auto` (browser language), `en` or `ru`; CLI output and feedback batches stay English |
+| `webTheme` | `vendor/vue.css` | docsify theme stylesheet |
+| `supportSearch` | `true` | search box in the sidebar |
+| `repoUrl` | `""` | repository link in the site corner |
+| `executeScript` | `false` | let docsify run `<script>` in pages (forced on by `openapi`) |
+| `docsifyTemplate` | `""` | path to a JS module exporting a function that returns `index.html` |
+| `webFileName` | — | fixed file name for every site page instead of the folder name |
+| `excludeSidebarFolderByPath` | — | array of folder paths, **including** `rootFolder` (`"src/2 Deployment"`), hidden from the sidebar |
+
+## Plugins
+
+| Key | Default | Meaning |
+|---|---|---|
+| `plugins` | `[]` | `"name"` or `["name", { options }]` — see [plugins.md](plugins.md). Unlike other keys, a malformed entry always fails the build |
+
+Legacy keys (`plantumlVersion`, `generatePDF`, `generateCompletePDF`) only produce a
+warning — remove them when you see one.
+
+Complete config written by `c4builder --new --name demo -y` — start from it when adding
+c4builder to an existing repository:
+
+```json
+{
+  "projectName": "demo",
+  "homepageName": "Overview",
+  "rootFolder": "src",
+  "distFolder": "docs",
+  "generateMD": true,
+  "generateCompleteMD": false,
+  "generateWEB": true,
+  "generateLLMS": true,
+  "includeNavigation": false,
+  "includeTableOfContents": true,
+  "webTheme": "vendor/vue.css",
+  "supportSearch": true,
+  "repoUrl": "",
+  "executeScript": false,
+  "docsifyTemplate": "",
+  "webPort": "3000",
+  "includeBreadcrumbs": true,
+  "includeLinkToDiagram": false,
+  "diagramsOnTop": true,
+  "embedDiagram": false,
+  "excludeOtherFiles": false,
+  "generateLocalImages": true,
+  "plantumlServerUrl": "https://www.plantuml.com/plantuml",
+  "diagramFormat": "svg",
+  "d2Layout": "dagre",
+  "charset": "UTF-8",
+  "useSystemFonts": false
+}
+```

package/skills/c4builder/references/diagrams.md

@@ -0,0 +1,77 @@
+# Diagrams reference
+
+The backend is chosen by file extension: `.puml` → PlantUML, `.d2` → D2, `.bpmn` → BPMN
+(validation + automatic layout + bpmn-js, see [bpmn.md](bpmn.md)), `.mmd` → mermaid (see
+[mermaid.md](mermaid.md)). All of them can live in one project and one folder (with different
+base names).
+
+## PlantUML and C4-PlantUML
+
+Rendering is offline: the PlantUML jar is bundled and runs on Java 17+ with the built-in
+Smetana layout — Graphviz is not used. `!pragma layout elk` needs Java 21.
+
+**C4 includes** come from the PlantUML stdlib (C4-PlantUML is inside the jar):
+
+| Level | Include | Main macros |
+|---|---|---|
+| System context | `!include <C4/C4_Context>` | `Person`, `System`, `System_Ext`, `Rel` |
+| Container | `!include <C4/C4_Container>` | `Container`, `ContainerDb`, `ContainerQueue`, `System_Boundary` |
+| Component | `!include <C4/C4_Component>` | `Component`, `ComponentDb`, `Container_Boundary` |
+| Dynamic | `!include <C4/C4_Dynamic>` | numbered `Rel` steps |
+| Deployment | `!include <C4/C4_Deployment>` | `Deployment_Node`, `Node` |
+
+Each level includes the previous ones. `LAYOUT_WITH_LEGEND()`, `LAYOUT_TOP_DOWN()`,
+`LAYOUT_LEFT_RIGHT()` control layout and legend. Do not include C4 by URL
+(`!include https://…`, `!includeurl`): it needs network on every build and pins nothing.
+
+**Shared styles** — one `.iuml` library included after the C4 include, by a path relative
+to the including diagram:
+
+```plantuml
+@startuml
+!include <C4/C4_Context>
+!include ../styles.iuml
+...
+@enduml
+```
+
+Put `skinparam`s and `UpdateElementStyle(...)` / `AddElementTag(...)` calls there. A `.iuml`
+is never rendered on its own; it is copied to the output like any other file (prefix it
+with `_` to keep it out). Editing an included file re-renders every diagram that includes
+it.
+
+**Other PlantUML diagrams** (sequence, class, activity, state, ditaa…) work the same way —
+any `@startuml` file is rendered. ditaa (`@startditaa`) always produces PNG.
+
+**Non-Latin text.** Sources are read as UTF-8 (`charset`). The bundled Nimbus Sans font
+covers Latin, Cyrillic and Greek, so diagrams look identical on every machine. Scripts it
+lacks (e.g. CJK) need `useSystemFonts: true` (or `c4builder --system-fonts` for one run)
+and a system font that has them — the output then depends on the machine.
+
+## D2
+
+`.d2` files are rendered by the bundled D2 engine (WASM → SVG), which is the optional npm
+dependency `@terrastruct/d2`. A `.d2` file in a project without it stops the build with an
+install hint. D2 has no online renderer, so `generateLocalImages` must stay `true`.
+
+- Imports: `@file` / spread `...@file` (without the `.d2` extension), resolved by
+  c4builder itself — no network. Keep shared classes in a `_`-prefixed file
+  (`src/_c4lib.d2`) and import it with `...@../_c4lib` from a nested folder.
+- Layout: `d2Layout` — `dagre` (default) or `elk`.
+- Validate like PlantUML: `c4builder check path/to/diagram.d2`.
+
+## Placement and output
+
+- Every diagram of a folder is attached to the folder's page; `![title](name.puml)` /
+  `![title](name.d2)` / `![title](name.bpmn)` / `![title](name.mmd)` in a markdown file of the same folder places it
+  inline instead.
+- Image file = diagram base name + `.svg` (or `.png` with `diagramFormat: png`), next to
+  the page in the output.
+- A ```` ```plantuml ```` block in a page `.md` is rendered at build time like a `.puml`
+  file and replaced by its image in every output (`@startuml` optional, `!include` relative
+  to the page folder, a broken block becomes a placeholder plus a warning). To show diagram
+  source as code, fence it as `puml` or `text` — those, like `d2` blocks, stay code. A
+  ```` ```mermaid ```` block is rendered the same way ([mermaid.md](mermaid.md)).
+- `embedDiagram: true` inlines images as base64; `includeLinkToDiagram: true` replaces
+  images with links.
+- Unchanged diagrams are reused from the previous build (checksums in `.c4builder.cache`).

package/skills/c4builder/references/mermaid.md

@@ -0,0 +1,78 @@
+# Mermaid reference
+
+Mermaid diagrams are rendered **at build time** by real mermaid (the official
+`@mermaid-js/tiny` build) running in jsdom — no browser, no network. Text is measured with
+the bundled Nimbus Sans, so the SVG is identical on every machine. Every output (site,
+markdown, complete markdown, PNG) gets an image; the browser never sees diagram source.
+
+## When mermaid, when PlantUML
+
+- **C4 model** (context, containers, components, deployment) — PlantUML with the C4 stdlib,
+  see [diagrams.md](diagrams.md). Mermaid C4 diagrams may lay out differently than in a browser.
+- **Mermaid** — flows and processes inside documentation and OpenSpec artifacts:
+  `flowchart`/`graph` (with `subgraph`), `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`,
+  `classDiagram`, `gantt`, `pie` and other types of the tiny build.
+- **Business processes with pools and lanes** — BPMN, see [bpmn.md](bpmn.md).
+
+## Two sources
+
+- **A `.mmd` file** in a page folder, like `.puml`/`.d2`/`.bpmn`: rendered to `<name>.svg`
+  (or `.png` with `diagramFormat: png`) and attached to the page, or placed inline with
+  `![title](flow.mmd)`. `flow.mmd` and `flow.puml` in one folder collide on the image name.
+- **A ```` ```mermaid ```` block** in a page `.md` or in an OpenSpec artifact (`design.md`,
+  `proposal.md`, specs): replaced by its image in every output, like a ```` ```plantuml ````
+  block. To show mermaid source as code instead, fence it as `text`.
+
+```mermaid
+sequenceDiagram
+    participant К as Клиент
+    participant Б as Банк
+    К->>Б: Заявка на счёт
+    Note right of Б: проверка анкеты
+    Б-->>К: Счёт открыт
+```
+
+## Conventions
+
+- Keep labels short. A label longer than ~200 px wraps at spaces; a single long word
+  without spaces is split by mermaid character by character.
+- Non-Latin text (Cyrillic etc.) works in ids and labels.
+- The look is fixed: `look: classic`, theme `default`, SVG text labels. `%%{init: …}%%` and
+  frontmatter `config:` cannot change `look`, `htmlLabels`, `fontFamily`, `securityLevel` or
+  `themeCSS`; other keys (`theme`, `flowchart.curve`, spacing) work as in mermaid.
+- Not supported: `mindmap`, `architecture` and KaTeX math (`$$…$$`) — they are not in the
+  tiny build and fail with an explicit `unsupported mermaid …` error.
+- Clicks, tooltips and links are not interactive: the image is static.
+
+## The loop
+
+```bash
+c4builder check "src/3 Processes/flow.mmd"
+```
+
+`check` parses and renders the file exactly like the build, without a project. Exit code 0
+means the diagram builds. Errors carry the line of the file (frontmatter and comments
+counted):
+
+```text
+✗ src/3 Processes/flow.mmd: line 3: ...A --> B  B -->> ((C; Expecting 'AMP', 'COLON', 'PIPE', ..., got 'TAGEND'
+✗ src/3 Processes/map.mmd: line 1: unsupported mermaid diagram type 'mindmap'
+```
+
+Fix the line and run `check` again until the exit code is 0, then build. A
+```` ```mermaid ```` block cannot be checked on its own: build the project and read the
+warnings, or copy the block into a temporary `.mmd`.
+
+- An error in a `.mmd` file fails the build with the file path and line.
+- An error in a ```` ```mermaid ```` block does not: the build exits with 0, the image is
+  a placeholder with the error, and the log has a warning naming the source `.md`.
+
+## Output and dependencies
+
+- In `llms-full.txt` a mermaid diagram (file or block) appears as its source in a
+  `mermaid` block.
+- The engine package `@mermaid-js/tiny` (about 2.7 MB, with `jsdom`) is an optional npm
+  dependency, loaded only when the project has mermaid. An install with `--omit=optional`
+  stops a `.mmd` build (and turns blocks into placeholders) with a hint to reinstall c4builder
+  without that flag.
+- Like D2 and BPMN, mermaid has no online renderer: `generateLocalImages` must stay `true`.

package/skills/c4builder/references/plugins.md

@@ -0,0 +1,68 @@
+# Plugins reference
+
+Plugins add pages from outside `rootFolder` (they go through the normal pipeline: sidebar,
+search, markdown outputs, local diagram rendering) and site assets. They are listed in
+`.c4builder`:
+
+```json
+{
+  "plugins": [
+    "openspec",
+    ["openapi", { "dir": "../contracts", "glob": "*/openapi.yaml" }]
+  ]
+}
+```
+
+- An entry is `"name"` or `["name", { options }]`. A malformed entry always fails the build.
+- Name resolution: built-in (`openspec`, `openapi`) → local ESM module
+  (`./plugins/my.mjs`, relative to the project) → npm package installed in the project.
+- Options are validated before the build; built-in plugins reject unknown option keys.
+- `${ENV_VAR}` inside string options is replaced from the environment (unset → empty) and
+  never printed — keep tokens there, not in the file.
+- Plugin folders are watched by `c4builder --site -w`.
+- Hooks run in list order; an exception aborts the build and names the plugin.
+
+## `openspec` — OpenSpec store as a site section
+
+Renders an [OpenSpec](https://github.com/Fission-AI/OpenSpec) store: a summary page
+(counters, task progress), one page per active change (header + first artifact, the other
+artifacts and spec deltas as subpages), the specs tree and the archive. `plantuml` / `d2`
+fenced blocks in artifacts are rendered by the local engines; a broken block gets a
+placeholder image and a warning naming the file instead of failing the build.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `dir` | `openspec` | store folder, relative to the project |
+| `mount` | `OpenSpec` | section name and its path in the output |
+| `artifacts` | `["proposal", "design", "tasks"]` | artifact order; the first is shown on the change page |
+| `parentKey` | — | `.openspec.yaml` key pointing at the parent change (e.g. `x-parent`); when set, child changes are nested under their parent in the sidebar, the Changes table and the archive |
+| `groupKey` | — | `.openspec.yaml` key with the change's group (e.g. `x-team`); when set, top-level changes go to `Changes/<group>/<id>`, the Changes table and the archive get per-group sections |
+| `nameKey` | — | `.openspec.yaml` key with the change's name (e.g. `x-name`); when set, the name labels the top-level change and is its page path segment (falls back to the id on `/`, `#`, `?` or a duplicate) |
+| `columns` | — | extra Changes table columns from `.openspec.yaml`: `[{ "key": "x-assignee", "title": "Assignee" }]`; missing value — `—` |
+
+## `openapi` — swagger-ui pages for OpenAPI specs
+
+One page per spec found by `glob` (named after the spec's parent folder) plus an index;
+swagger-ui is bundled, readers need no network. Exactly one source — `dir` **or**
+`archive` — is required. It forces `executeScript: true`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `mount` | `API` | section name |
+| `dir` | — | local folder with specs (watched) |
+| `archive` | — | HTTP(S) URL of a `tar.gz` / `zip` archive (e.g. a repository archive) |
+| `subdir` | — | folder inside the archive or `dir` |
+| `headers` | — | HTTP headers for the archive request, e.g. `{"PRIVATE-TOKEN": "${GITLAB_TOKEN}"}` |
+| `glob` | `**/openapi.{yaml,yml,json}` | spec pattern (`**`, `*`, `?`, `{a,b}`); directories starting with a dot are skipped |
+
+All `yaml`/`yml`/`json` files of the source are published under `<mount>/_specs/…` with
+their relative layout, so relative `$ref`s keep working. Archive download fails with
+`self-signed certificate in certificate chain` behind a TLS-intercepting proxy → set
+`NODE_EXTRA_CA_CERTS` to the proxy CA bundle.
+
+## Custom plugins
+
+A plugin is an ESM module whose default export is an object with `name` and optional
+`options` (zod schema), `watchPaths`, `assets`, `requires`, `afterScan(ctx, opts)` (add
+virtual pages with `ctx.addPage`) and `afterBuild(ctx, opts)`. See the "Writing a plugin"
+section of the c4builder README for the full contract and an example.

package/skills/c4builder-review/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: c4builder-review
+description: Review c4builder pages with a human right on the local site - the human selects text in c4builder --site -w and leaves comments with the Feedback button, the agent receives them in batches with c4builder feedback --wait --as <name>, edits the sources and waits for the next batch until Approve. Use when asked to discuss a change on the site, to show the pages or a design, to review a page, the design or OpenSpec artifacts, when the human says they will leave comments on the page, right after proposing an OpenSpec change in a repository with c4builder, and on /c4builder-review [change-id|page].
+---
+
+# c4builder-review: page comments to the agent
+
+The human looks at the pages in the browser (`c4builder --site -w`), selects text and presses:
+
+- **Feedback** — a comment to you. It is not written to the files and comes to you in a batch:
+  **Send now** sends one comment, **Add to review** → **Submit review** sends several (from several
+  pages too), **Approve** means nothing more to change.
+- **Question** — a question for people: c4builder appends it to the source `.md` under the
+  `questionsHeading` section (`Open questions` by default). It is not a task for you — leave it
+  alone unless asked.
+
+Invocation: `/c4builder-review [change-id|page]`. The port is `webPort` from `.c4builder`
+(`<port>` below); when the server runs with `-p <n>`, pass the same `-p <n>` to the commands below.
+
+The listener name (`<name>` below) is how the page picks the agent when several share one
+`site -w`: the change id from the argument, otherwise the name of your task. Letters, digits,
+`.`, `_`, `-`, up to 64 characters. Keep one name for the whole review.
+
+## 1. Server
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<port>/
+```
+
+`200` — the server is up; never start a second one. Otherwise ask the user to start
+`c4builder --site -w`, or ask whether you may start it yourself in the background — many teams
+keep the preview server in the human's hands.
+
+## 2. Link
+
+- Argument is an OpenSpec change id: find its page in the build output (`distFolder` from
+  `.c4builder`, `docs` by default). The path depends on the `mount`, `groupKey` and `nameKey`
+  options of the `openspec` plugin — search, do not guess:
+  `find <distFolder> -path '*<change-id>*' -name '*.md' | head` (with `nameKey` the folder carries
+  the change's name from its `.openspec.yaml` instead of the id). The address is
+  `http://localhost:<port>/#/<path without .md>`.
+- Argument is a page or a section: find it in the build output the same way.
+- No argument: the home page `http://localhost:<port>/`.
+
+Give the link, remind in two lines what **Feedback** and **Question** do (see above) and say your
+listener name: with several agents the human picks it in **Send to** on the review bar.
+
+## 3. Wait
+
+Start in the background (in Claude Code: Bash with `run_in_background`):
+
+```bash
+c4builder feedback --wait --as <name>
+```
+
+It exits when a batch arrives; its stdout is the batch. Connecting turns the **Feedback** button
+on by itself, the server needs no restart. Errors:
+
+- `--as <name> is required` (exit code 2) — the name is missing or invalid: fix it and run again;
+- `no c4builder site -w on …` (exit code 1) — no server or it crashed: back to step 1;
+- `agent feedback is disabled on …` (exit code 1) — the server runs without `-w` or with
+  `--no-agent`: ask the user to restart `c4builder --site -w`;
+- `unknown command: feedback` or `unknown option '--as'` — the CLI is older than this skill: tell
+  the user, `c4builder update` updates it (only when they agree).
+
+## 4. Batch
+
+```text
+# Page feedback (c4builder)
+
+Decision: submitted
+Comments: 1 on 1 page
+
+## 1. OpenSpec/Changes/add-dark-mode/design.md (§ D3)
+Sources: openspec/changes/add-dark-mode/design.md
+Quote: "the selected text"
+
+> what to change
+```
+
+Every comment names the site page, the page section (`§`), its source files (`Sources`) and the
+quoted selection; `## General` is the overall comment of a review.
+
+- Edit the files listed in `Sources` (change artifacts, `src/` and so on), never the build output.
+  No `Sources` — find the quote in the sources (`grep -rn`). The page reloads by itself.
+- Do not copy comments into the questions section: they are instructions to you, not questions
+  for people.
+- A comment that is unclear or debatable — ask in the chat instead of guessing; do the rest of the
+  batch.
+- After the edits report briefly in the chat what you did for each comment number. Then run
+  `c4builder feedback --wait --as <name>` in the background again with the same name — batches
+  wait in your mailbox.
+
+## 5. Done
+
+`Decision: approved` — nothing more to change: apply the comments of that batch, if any, give a
+summary of the changes by file and stop waiting. Do not commit unless the user asks.

package/skills/c4builder-setup/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: c4builder-setup
+description: Install, update and diagnose c4builder (npm package @alfacapital-tech/c4builder), the CLI that builds C4 / PlantUML / D2 architecture docs into a docsify site or markdown, and install its agent skills into a project. Use when asked to install or upgrade c4builder, when the c4builder command is missing or fails to render diagrams, when switching between the stable and release-candidate channels, or when onboarding onto a repository documented with c4builder. Optional argument - channel rc; default is the stable latest. Idempotent - a re-run only verifies.
+---
+
+# c4builder setup
+
+Goal: a `c4builder` that really renders diagrams, and its skills in the working project.
+`c4builder --version` alone proves nothing — the smoke build (step 5) does.
+
+**Channel.** `latest` — stable (default); `rc` — release candidates (`X.Y.Z-rc.N`). npm
+dist-tags and Docker image tags carry the same names.
+
+Every step: check → fix only what is broken.
+
+## 1. Node.js
+
+```bash
+node --version   # needs >= 22.17
+```
+
+Missing or older → agree with the user on how to install a current LTS (nvm, OS package
+manager, official installer); do not pick a method silently. Docker users skip to step 3.
+
+## 2. Installed version vs. channel
+
+```bash
+c4builder --version
+npm view @alfacapital-tech/c4builder dist-tags
+```
+
+`npm view` fails with a network or certificate error → the public registry may be closed in
+this network. An organization mirror is configured in the user's npmrc (`npm config get
+registry` shows the current one) or passed per command with `--registry <url>`; ask the user for
+the address, never guess one. The update check of c4builder and `c4builder update` use the same
+npmrc.
+
+Installed version equals the channel's tag → skip step 3.
+Installed version is **newer** than the requested channel (an `rc` while `latest` was
+asked for) → that is a downgrade: never do it silently, confirm with the user — they
+probably want the `rc` channel.
+
+## 3. Install / update
+
+```bash
+npm install -g @alfacapital-tech/c4builder@latest   # stable
+npm install -g @alfacapital-tech/c4builder@rc       # release candidate
+```
+
+- An installed global CLI is updated with `c4builder update`: it installs the newest version
+  (`latest`; on a release candidate the newer of `latest` and `rc`). For a project dependency
+  or the Docker image it installs nothing and prints the command to use instead. Switching the
+  channel is the `npm install -g` line above.
+- Do not pass `--omit=optional`: the D2 engine (`@terrastruct/d2`) is an optional
+  dependency; without it a project with `.d2` files stops with an install hint.
+- `c4builder: command not found` after a successful install → the global npm bin folder
+  is not on `PATH` (`npm prefix -g` shows the prefix; the binary lives in its `bin`).
+
+**Docker instead of npm** — the image ships Node, a JRE, the PlantUML jar, fonts and D2,
+so steps 1 and 4 are not needed. Mount the project into `/pwd`:
+
+```bash
+docker run --rm -v "$PWD:/pwd" ghcr.io/alfacapital-tech/c4builder:latest c4builder
+```
+
+Image tags: `latest`, `rc`, `X.Y.Z`, `edge` (last master commit). The same image works as a
+CI job image — `c4builder` is on `PATH`.
+
+## 4. Java for PlantUML
+
+Diagrams are rendered by the bundled PlantUML jar → Java 17+ is needed (`JAVA_HOME` is
+checked first, then `PATH`). Graphviz is **not** needed.
+
+```bash
+java -version
+c4builder jre install
+```
+
+`c4builder jre install` reports a suitable system java and stops; otherwise it downloads a
+private Temurin JRE into the user cache once — tell the user it did. A broken system java
+can be bypassed with `c4builder jre install --force` (downloads even when java is present).
+`c4builder jre info` prints the managed JRE parameters as JSON (Temurin major, cache
+folder) — use it to key a CI cache.
+
+Download fails with a certificate error (TLS-intercepting proxy) → set
+`NODE_EXTRA_CA_CERTS` to the proxy's CA bundle; Node reads neither the system store nor
+`SSL_CERT_FILE`.
+
+## 5. Smoke build
+
+Build the bundled template project in a temporary folder:
+
+```bash
+cd "$(mktemp -d)"
+c4builder --new --name smoke -y
+cd smoke
+c4builder
+ls docs/index.html docs/context.svg
+```
+
+`--new --name smoke -y` creates the project with default settings and no prompts; the
+plain `c4builder` run is a one-off build. Both files listed → Node, CLI, Java/PlantUML and
+the site generator work. `index.html` without `context.svg`, or a non-zero exit code →
+rendering problem: read the error, return to step 4 (Java) or step 3 (D2 hint). Remove the
+temporary folder afterwards.
+
+With Docker, run the same two commands through the image: `c4builder --new --name smoke -y`
+in the temporary folder, then the plain build with `smoke` mounted as `/pwd`.
+
+## 6. Skills in the working project
+
+In the root of the user's project (not the temporary one):
+
+```bash
+c4builder skills
+```
+
+It installs the skills of the installed CLI version into `.agents/skills/` (and `.claude/skills/`
+under Claude Code or when `.claude/` exists), replacing only the c4builder skills there; each
+installed `SKILL.md` carries `metadata.generatedBy: <version>`. These are files in the user's
+repository — run it when the user asked for the setup of this project, otherwise ask first. A
+stderr line `~/.claude/skills/c4builder (…) overrides project skills` means a stale personal copy
+(for example from `npx skills add -g`) shadows them: tell the user, remove it only with their
+consent. A project created with `c4builder --new` already has the skills.
+
+## Report
+
+One short summary: Node version / c4builder version and channel / Java (system or managed
+JRE) / smoke build / skills in the project — each OK or fixed. For working on the diagrams
+themselves, use the `c4builder` skill.

package/template/AGENTS.md

@@ -34,6 +34,9 @@ updates it.
    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.
+5. A stderr line ending with `Ask the user, then run: c4builder skills` means the c4builder skills
+   here are missing, outdated or shadowed by a personal copy: tell the user, run `c4builder skills`
+   (or remove the personal copy) only if they agree.
 
 ## Layout
 
@@ -60,8 +63,16 @@ updates it.
 
 ## Agent skills
 
-Detailed guidance (project layout, config keys, plugins, installation) as skills for
-Claude Code, Codex, Cursor and other agents:
+Detailed guidance (project layout, config keys, plugins, page review, installation) as skills for
+Claude Code, Codex, Cursor and other agents. A project created with `c4builder --new` already has
+them in `.agents/skills/` (and `.claude/skills/` under Claude Code). Install or update them to the
+installed CLI version:
+
+```bash
+c4builder skills
+```
+
+Alternative, also for a personal install (`-g`) and other agents' folders:
 
 ```bash
 npx skills add AlfaCapital-Tech/C4-Builder/skills