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

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.