# BPMN Kit — Full Content

> A TypeScript SDK for building, modeling, simulating, and deploying BPMN processes on Camunda 8.

---

## What is BPMN Kit?

BPMN Kit is an open-source TypeScript monorepo that makes it possible to work
with BPMN 2.0 processes entirely in code. Instead of wrestling with hundreds of
lines of raw XML and manual coordinates, you call a fluent TypeScript API and
get back valid, auto-laid-out BPMN XML ready to deploy to Camunda 8.

The SDK is AI-native: a compact intermediate format lets an entire diagram fit
in a single LLM prompt. AI agents can generate, read, and modify process
definitions without ever seeing raw XML.

Every package is strict-TypeScript, ESM-only, tree-shakeable, and runs in
browsers, Node.js, Deno, Bun, and edge runtimes.

---

## Packages

- [@bpmnkit/core](https://github.com/bpmnkit/bpmnkit/tree/main/packages/core): Fluent process builder, BPMN 2.0 parser/serializer, DMN support, AI-compact format (compactify/expand), auto-layout (Sugiyama algorithm), SVG export (zero third-party deps, all runtimes). Multi-process support: Bpmn.createDiagram() assembles caller/callee process pairs in one definitions document. Full branching inside sub-processes (exclusiveGateway, parallelGateway, branch()). Ergonomic boundary events via withBoundary() — cursor auto-restores to main flow after the error path. Includes 29 TypeScript type guard predicates (isBpmnServiceTask, isBpmnGateway…), typed error classes (ParseError, ValidationError — instanceof-catchable), and element lookup utilities (findElement, getZeebeExtensions, etc.)
- [@bpmnkit/engine](https://github.com/bpmnkit/bpmnkit/tree/main/packages/engine): BPMN simulation engine, zero third-party dependencies (browser + Node.js) — service tasks, user tasks, gateways, timers, message correlation, DMN evaluation
- [@bpmnkit/api](https://github.com/bpmnkit/bpmnkit/tree/main/packages/api): Camunda 8 REST API client — 180 typed methods, 30+ resource classes, OAuth2 / Bearer / Basic auth, LRU+TTL cache, exponential backoff, TypedEventEmitter
- [@bpmnkit/canvas](https://github.com/bpmnkit/bpmnkit/tree/main/packages/canvas): Zero-third-party-dependency SVG BPMN viewer with pan/zoom, dark/light theme, plugin API
- [@bpmnkit/editor](https://github.com/bpmnkit/bpmnkit/tree/main/packages/editor): Full BPMN editor — canvas + properties panel + AI bridge + storage
- [casen (CLI)](https://github.com/bpmnkit/bpmnkit/tree/main/apps/cli): Interactive TUI for managing Camunda 8 from the terminal: processes, jobs, incidents, decisions, variables, messages

---

## Key Features

- Fluent builder API: chain .startEvent().serviceTask().exclusiveGateway().branch()...
- Multi-process definitions: Bpmn.createDiagram(id) assembles multiple processes (caller/callee, sub-flows) into one BPMN definitions document
- Sub-process branching: full gateway and branch() support inside subProcess() callbacks, with auto-join insertion
- Ergonomic boundary events: .withBoundary(id, options, handler) attaches error/timeout paths and auto-restores the main flow cursor
- Auto-layout: Sugiyama algorithm produces clean diagrams with no coordinate math
- AI-native: compact intermediate format fits an entire diagram in a single LLM prompt
- Camunda 8 ready: native Zeebe task definitions, IO mappings, connectors, forms
- Roundtrip fidelity: parse → modify → export without data loss
- SVG export: generate diagram images from BpmnDefinitions — zero third-party deps, works in Node.js, browser, Deno, Bun
- Type guards: 29 predicates (isBpmnServiceTask, isBpmnGateway…) narrow BpmnFlowElement unions at compile time
- Typed errors: ParseError and ValidationError extend a common BpmnSdkError base — all instanceof-catchable with error codes
- Element lookup utilities: findElement, findProcess, getZeebeExtensions and friends traverse parsed diagrams
- Full JSDoc coverage: @param, @returns, @throws, @example on every public API
- Simulation engine: deploy and run processes locally, register job workers, evaluate DMN
- REST API client: full Camunda 8 Orchestration Cluster API coverage
- CLI: arrow-key TUI, connection profiles, tabular results

---

## Core SDK (@bpmnkit/core)

### Basic Process

```typescript
import { Bpmn } from "@bpmnkit/core";

const xml = Bpmn.export(
  Bpmn.createProcess("my-flow") // fluent API
    .startEvent("start")        // trigger
    .serviceTask("task", {
      name: "Do Something",
      taskType: "my-worker",    // Zeebe type
    })
    .endEvent("end")
    .withAutoLayout()           // Sugiyama
    .build()
);

// ✓ Valid BPMN 2.0 XML
// ✓ Auto-layout applied
// ✓ Zeebe extensions set
```

### Exclusive Gateway (Branching)

```typescript
const xml = Bpmn.export(
  Bpmn.createProcess("approval-flow")
    .startEvent("start", { name: "Request Submitted" })
    .userTask("review", { name: "Review Request" })
    .exclusiveGateway("gw", { name: "Approved?" })
    .branch("yes", (b) =>
      b.condition("= approved")
        .serviceTask("notify", { taskType: "send-email" })
        .endEvent("end-ok")
    )
    .branch("no", (b) => b.defaultFlow().endEvent("end-no"))
    .withAutoLayout()
    .build()
);
```

### Parallel Gateway

```typescript
const xml = Bpmn.export(
  Bpmn.createProcess("order-fulfillment")
    .startEvent("start")
    .parallelGateway("split")
    .branch("warehouse", (b) =>
      b.serviceTask("pick", { taskType: "warehouse-pick" })
    )
    .branch("payment", (b) =>
      b.serviceTask("charge", { taskType: "payment-charge" })
    )
    .parallelGateway("join")
    .endEvent("end")
    .withAutoLayout()
    .build()
);
```

---

## Simulation Engine (@bpmnkit/engine)

Run BPMN processes locally in the browser or Node.js. Zero external
dependencies. Supports service tasks, user tasks, exclusive/parallel/event-based
gateways, timers, message correlation, and DMN decision evaluation.

```typescript
import { Engine } from "@bpmnkit/engine";

// Simulate the process in-process — for tests and local development.
// Deploying to a real Camunda 8 cluster? See the API client below.
const engine = new Engine();
engine.deploy({ bpmn: defs });

engine.registerJobWorker(
  "greet",
  async (job) => {
    console.log("Hello!");
    job.complete();
  }
);
engine.start("hello");
```

---

## REST API Client (@bpmnkit/api)

```typescript
import { CamundaClient } from "@bpmnkit/api";

const client = new CamundaClient({
  baseUrl: "https://api.cloud.camunda.io",
  auth: {
    type: "oauth2",
    clientId:     process.env.CAMUNDA_CLIENT_ID!,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET!,
    tokenUrl:     "https://login.cloud.camunda.io/oauth/token",
    audience:     process.env.CAMUNDA_AUDIENCE!,
  },
});

// Start a new instance of an already-deployed process
const instance = await client.processInstance.createProcessInstance({
  processDefinitionId: "my-flow",
  variables: { orderId: "ord-123" },
});

// React to lifecycle events
client.on("request", (e) => console.log(e.method, e.url));
client.on("error",   (e) => metrics.inc("api.error"));
```

Resource coverage: Processes, Jobs & Workers, Decisions (DMN), Messages,
Incidents, Variables, Signals, User Tasks, Authorizations, Groups, Users.

Non-functional: LRU+TTL cache, exponential backoff, TypedEventEmitter,
ESM tree-shakeable, zero transitive runtime dependencies.

---

## CLI — casen

Interactive TUI for managing Camunda 8. Navigate with arrow keys.

```
casen
```

Main menu groups: profile, process, job, incident, decision, variable, message.

Example — list deployed process definitions:

  Navigate to: process → list → Enter

  Result:
    bpmnProcessId             name                   ver
    ─────────────────────────────────────────────────────
  ▶ order-validation           Order Validation        1
    payment-processing         Payment Processing      2
    ai-support-agent           AI Support Agent        1
    approval-flow              Approval Flow           3

---

## Getting Started

### 1. Install

```
pnpm add @bpmnkit/core
```

### 2. Create a process

```typescript
import { Bpmn, exportSvg } from "@bpmnkit/core";

const defs = Bpmn.createProcess("hello")
  .startEvent("start")
  .serviceTask("task", {
    name: "Hello World",
    taskType: "greet",
  })
  .endEvent("end")
  .withAutoLayout()
  .build();

const xml = Bpmn.export(defs); // ✓ BPMN 2.0 XML
const svg = exportSvg(defs);   // ✓ SVG image, zero deps
```

### 3. Deploy and run

```typescript
import { Engine } from "@bpmnkit/engine";

// Simulate the process in-process — for tests and local development.
// Deploying to a real Camunda 8 cluster? See the API client below.
const engine = new Engine();
engine.deploy({ bpmn: defs });

engine.registerJobWorker(
  "greet",
  async (job) => {
    console.log("Hello!");
    job.complete();
  }
);
engine.start("hello");
```

---

## Documentation — Getting Started

### Installation

Install BPMN Kit packages in your project.

Source: https://bpmnkit.com/docs/getting-started/installation

BPMN Kit is a collection of focused packages. Install only what you need.

## Core SDK

The `@bpmnkit/core` package is the foundation — it provides the fluent process builder,
BPMN 2.0 parser/serializer, auto-layout, and the AI-compact format.

```sh
pnpm add @bpmnkit/core
# or
npm install @bpmnkit/core
# or
yarn add @bpmnkit/core
```

## Simulation Engine

To run BPMN processes locally (browser or Node.js):

```sh
pnpm add @bpmnkit/engine
```

## Camunda 8 REST API Client

To interact with a live Camunda 8 cluster:

```sh
pnpm add @bpmnkit/api
```

## SVG Canvas Viewer

To embed an interactive BPMN diagram viewer in a web page:

```sh
pnpm add @bpmnkit/canvas
```

## Full Editor

The editor bundles the canvas, a properties panel, and an AI bridge:

```sh
pnpm add @bpmnkit/editor
```

## CLI

The `casen` CLI is a standalone tool — install it globally:

```sh
pnpm add -g @bpmnkit/cli
```

With the CLI installed, you can use the AI-first workflow to implement processes from natural
language using Claude Code:

```sh
casen skills install   # install /implement, /review, /test, /deploy slash commands
casen proxy            # start the AI bridge
casen reebe            # start local workflow engine
```

Then in Claude Code: `/implement an invoice approval process`

See [AI-Driven Implementation](/docs/guides/ai-implement) for a full walkthrough.

## Worker client

For standalone workers that connect to Zeebe without the full SDK:

```sh
npm install @bpmnkit/worker-client
```

Workers scaffolded by `/implement` depend only on this package at runtime.

## TypeScript Requirements

All packages require **TypeScript 5.0+** with `strict: true`. The recommended `tsconfig.json` settings:

```json
{
  "compilerOptions": {
    "strict": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022"
  }
}
```

For browser/bundler projects (Vite, Webpack, etc.), use:

```json
{
  "compilerOptions": {
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}
```

## Runtime Requirements

| Runtime | Minimum Version |
|---|---|
| Node.js | 20 LTS |
| Deno | 1.40+ |
| Bun | 1.0+ |
| Browsers | ES2022 (Chrome 94, Firefox 93, Safari 15.4) |

All packages are **ESM-only** (`"type": "module"`). CommonJS is not supported.

---

### Quick Start

Build and run your first BPMN process in minutes.

Source: https://bpmnkit.com/docs/getting-started/quick-start

This guide walks you from zero to a deployed, running BPMN process in three steps.

## Step 1: Create a process

Use the fluent builder to describe your process in TypeScript:

```typescript
import { Bpmn } from "@bpmnkit/core";

const xml = Bpmn.export(
  Bpmn.createProcess("hello")
    .startEvent("start")
    .serviceTask("task", {
      name: "Hello World",
      taskType: "greet",   // Zeebe worker type
    })
    .endEvent("end")
    .withAutoLayout()      // apply Sugiyama layout
    .build()
);

console.log(xml); // valid BPMN 2.0 XML
```

The `xml` string is a complete, valid BPMN 2.0 document that any standards-compliant engine can load.

## Step 2: Simulate locally

The simulation engine runs the process right in Node.js — no Camunda cluster required:

```typescript
import { Engine } from "@bpmnkit/engine";

const engine = new Engine();
await engine.deploy({ bpmn: xml });

// Register a job worker for the "greet" service task
engine.registerJobWorker("greet", async (job) => {
  console.log("Hello from the worker!");
  await job.complete({ greeting: "Hello!" });
});

const instance = engine.start("hello");

// Wait for the process to finish
await new Promise<void>((resolve) => {
  instance.onChange((state) => {
    if (state === "completed") resolve();
  });
});
```

Prefer to see it? Write `xml` to `hello.bpmn` and run [`casen dev`](/docs/cli/dev) in that
folder: the editor opens in your browser with the simulator, and every save is linted and runs
the file's scenario tests.

```sh
npx @bpmnkit/cli dev
```

## Step 3: Deploy to Camunda 8

When you're ready for production, deploy to a real Camunda 8 cluster:

```typescript
import { CamundaClient } from "@bpmnkit/api";

const client = new CamundaClient({
  baseUrl: "https://api.cloud.camunda.io",
  auth: {
    type: "oauth2",
    clientId: process.env.CAMUNDA_CLIENT_ID,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
    audience: process.env.CAMUNDA_AUDIENCE,
  },
});

// Deploy the process definition
await client.process.deploy({
  resources: [{ content: xml, name: "hello.bpmn" }],
});

// Start a new process instance
const instance = await client.process.startInstance({
  bpmnProcessId: "hello",
  variables: { greeting: "world" },
});

console.log("Started instance:", instance.processInstanceKey);
```

## What's next?

- [AI-Driven Implementation](/docs/guides/ai-implement) — let Claude implement processes end-to-end from a description
- [Core Concepts](/docs/getting-started/concepts) — understand how the builder, layout, and roundtrip work
- [Building Processes](/docs/guides/building-processes) — tasks, events, sub-processes, and markers
- [Gateways & Branching](/docs/guides/gateways) — exclusive, parallel, and event-based gateways

> **AI-first workflow** — if you have Claude Code, the fastest path is `casen skills install`
> then `/implement <description>`. Claude generates the BPMN, scaffolds workers, and deploys —
> all from a single prompt.

---

### Core Concepts

Understand how the builder, serializer, auto-layout, and AI-compact format work.

Source: https://bpmnkit.com/docs/getting-started/concepts

## The Fluent Builder

`Bpmn.createProcess(id)` returns a `ProcessBuilder` — a chainable object that tracks the
current "cursor" position in the process graph. Each method call appends an element and
advances the cursor:

```typescript
import { Bpmn } from "@bpmnkit/core";

Bpmn.createProcess("my-process")
  .startEvent("start")       // cursor at startEvent
  .serviceTask("task-1")     // cursor at task-1; sequence flow start → task-1 added
  .endEvent("end")           // cursor at end; sequence flow task-1 → end added
  .build();
```

### Sequential flow

Methods like `.serviceTask()`, `.userTask()`, `.scriptTask()`, and `.endEvent()` all create an
element _and_ a sequence flow from the previous cursor position.

### Branches

`.exclusiveGateway()` and `.parallelGateway()` create a gateway and advance the cursor to it.
Use `.branch(id, builder)` to define outgoing paths:

```typescript
.exclusiveGateway("gw")
.branch("approved", (b) =>
  b.condition("= approved").serviceTask("notify").endEvent("done")
)
.branch("rejected", (b) =>
  b.defaultFlow().endEvent("rejected")
)
```

Each branch builder starts at the gateway. Branches merge automatically when two paths lead to
the same element.

## Auto-Layout

Call `.withAutoLayout()` before `.build()` to apply the Sugiyama layered graph algorithm.
It produces clean, left-to-right layouts without any coordinate math:

```typescript
const process = Bpmn.createProcess("flow")
  .startEvent("start")
  .serviceTask("work")
  .endEvent("end")
  .withAutoLayout()   // assigns x/y/width/height to all elements
  .build();
```

Under the hood, the layout algorithm:
1. Topologically sorts elements into layers
2. Assigns X coordinates based on layer depth
3. Assigns Y coordinates by crossing-minimisation within each layer
4. Adds waypoints to sequence flow edges

You can access element sizes via the `ELEMENT_SIZES` export if you need to build custom layouts.

## Parsing and Serializing

Parse BPMN 2.0 XML into a typed object, modify it in TypeScript, and export it back:

```typescript
import { Bpmn, findProcess } from "@bpmnkit/core";

// Parse XML into a typed object
const definitions = Bpmn.parse(xmlString);

// Access the first process, or look one up by id
const process = definitions.processes[0];
const approval = findProcess(definitions, "approval-flow");

// Export back to XML
const newXml = Bpmn.export(definitions);
```

### Round-trip fidelity

`Bpmn.parse()` → `Bpmn.export()` preserves the document. Content the SDK models round-trips
through its typed fields; content it does not model is kept verbatim and re-emitted:

- **Unmodelled attributes** land in `unknownAttributes` on the element that carried them.
- **Unmodelled children** of `definitions`, a `process`, a `collaboration`, a flow node, a
  sequence flow, a `multiInstanceLoopCharacteristics` or a data association land in
  `unknownChildren` — so
  `bpmn:import`, `bpmn:itemDefinition`, `bpmn:ioSpecification`, `bpmn:correlationKey`,
  `bpmn:potentialOwner`, `bpmn:complexBehaviorDefinition` and vendor elements outside
  `extensionElements` all survive, including their nested content.
- **`extensionElements`** are kept as raw `XmlElement` trees wherever BPMN allows them,
  including on root-level `message`, `error`, `escalation` and `signal` elements — which is
  what carries `zeebe:subscription` correlation keys — and on data associations.
- **Diagram interchange from other tools** survives too: `BPMNLabelStyle` fonts, attributes
  on `BPMNDiagram`, `BPMNPlane`, `BPMNLabel` and waypoints, and DI elements that omit the
  optional `id` or `bpmnElement` (read as `""` and written back absent).
- **Namespaces are kept as the file declared them.** A model that puts BPMN in the default
  namespace — common in files from Signavio, Trisotech and Visio add-ins — is written back
  with unprefixed names, not rewritten to `bpmn:`.

`semanticHash(definitions)` gives you this as a check you can run yourself: it hashes the
model with the diagram excluded, so `semanticHash(applyAutoLayout(defs))` equals
`semanticHash(defs)`, and any difference means the model changed rather than the layout.

A corpus of BPMN documents is round-tripped on every build and compared structurally —
element counts, per-element attribute names, parent/child nesting and text content, keyed by
namespace rather than prefix — by a scanner written independently of the parser, so a
regression fails CI rather than reaching a release. The corpus includes all 22 reference
models of the [OMG BPMN Model Interchange test suite](/docs/getting-started/conformance#bpmn-model-interchange-miwg).
See `packages/core/tests/roundtrip-corpus.test.ts`.

A second gate works from the other direction. The corpus can only find losses in documents
somebody wrote; this one asks the BPMN, DI and Zeebe schema descriptors what exists at all,
builds a document containing each of the 151 types they define, and requires it to come back
out — as a typed field or verbatim. A descriptor bump that widens the specification fails the
build instead of quietly widening the loss. See
`packages/core/tests/descriptor-coverage.test.ts`, or run
`pnpm --filter @bpmnkit/core check:descriptors` for the report.

**Deliberate normalisations.** The output is not byte-identical to the input, and two rewrites
are intentional:

- `isExecutable`, `isSequential`, `isForCompensation` and `isCollection` are written only
  when true. BPMN treats the absent attribute as false, so this is stable and changes
  nothing.
- Empty `<extensionElements/>` elements are dropped, and whitespace and attribute order are
  not preserved.

**Still not preserved.** Unmodelled *children* are captured on the containers listed above
only. On other elements — lanes, artifacts, root-level messages and errors —
`documentation` and `extensionElements` round-trip, but any other unrecognised child does
not. A second `<documentation>` on the same element is also dropped;
only the first is kept, with its attributes. If you need one of these, open an issue rather
than working around it.

`exportPreserving` goes further than `Bpmn.export`: it writes the model into the original
file's own bytes, so an unchanged model comes back byte for byte — including a coordinate
spelled `30.0` and an empty `<extensionElements/>`, which a plain export normalises.

## AI-Compact Format

Raw BPMN XML is verbose — a simple three-node process takes ~60 lines of XML. The compact
format reduces this to a small JSON object that fits in a single LLM prompt:

```typescript
import { compactify, expand } from "@bpmnkit/core";

// Definitions → CompactDiagram (small JSON)
const compact = compactify(definitions);

// CompactDiagram → Definitions (full object)
const restored = expand(compact);
```

The compact format is designed for AI agents:
- Every element has an `id` and a human-readable `name`
- Sequence flows are represented as `{ from, to, condition? }` pairs
- Common Zeebe extensions (task type, headers, form and decision bindings) are inlined
- The full diagram of a typical approval workflow fits in ~500 tokens

> **`compactify()` is a lossy view, not a round trip.** `CompactElement` models about fifteen
> properties, so `expand(compactify(definitions))` is not `definitions`: collaborations,
> participants, message flows, lanes, data stores, artifacts, root-level messages and errors,
> multi-instance loop characteristics, full `zeebe:ioMapping` entries and most diagram
> interchange do not survive it.
>
> Use it to **show** a model to an LLM and to build a **new** model from one. Do not use it as
> an edit path for a file you need to keep — read the file, apply the change to the
> `BpmnDefinitions`, and export that. For the same reason `casen generate bpmn --input`
> refuses to overwrite its input unless you pass `--force`.

## Zeebe Extensions

Camunda 8 (Zeebe) uses XML extension elements for its engine-specific config.
The builder exposes these as first-class TypeScript options:

```typescript
.serviceTask("send-email", {
  name: "Send Confirmation Email",
  taskType: "io.camunda.connectors.SMTP.v1",   // connector type
  taskHeaders: {
    from: "noreply@example.com",
    subject: "Your order is confirmed",
  },
  inputMappings: [
    { source: "= orderId", target: "orderId" },
    { source: "= customer.email", target: "to" },
  ],
  outputMappings: [
    { source: "= messageId", target: "emailMessageId" },
  ],
})
```

---

### Stability and Versioning

What a version number promises — what counts as a breaking change, what is public API, and how long each release is supported.

Source: https://bpmnkit.com/docs/getting-started/stability

## What this page is for

A version number is a promise about breakage. This page says exactly which promise BPMN Kit
makes, so you can decide what to write in your `package.json` and know what an upgrade can
do to you.

Every package follows [Semantic Versioning 2.0.0](https://semver.org). The rest of this page
is the part semver leaves open: what counts as *the API* in a toolkit that also emits XML
files, writes state to disk and speaks HTTP.

## What is covered today

The promises below take effect for a given package **when it reaches 1.0.0**. Twelve packages
do — they are listed at the end of this page. A package still on 0.x is **not** covered by
them, even though other packages in the workspace are: under semver, 0.x makes no
compatibility promise at all. Releases of those have been additive in practice, but *in
practice* is not a contract, so pin an exact version if one of them matters to you.

## Product tiers

Every product BPMN Kit ships is in one of three tiers. The tier says how much you can rely
on it. Each README and each package page on this site shows it.

| Tier | What it promises |
|---|---|
| **Core** | The promises on this page, from 1.0: nothing breaks without a major release. Core is exactly the twelve packages at 1.0. |
| **Tools** | Maintained: bugs are fixed and releases continue. Versions are 0.x, so a minor release can break. Pin a version. |
| **Experimental** | May change a lot or be discontinued. Not for production. Always below 1.0. |

- **Core:** `@bpmnkit/core`, `@bpmnkit/canvas`, `@bpmnkit/editor`, `@bpmnkit/plugins`,
  `@bpmnkit/engine`, `@bpmnkit/feel`, `@bpmnkit/api`, `@bpmnkit/ascii`, `@bpmnkit/docspack`,
  `@bpmnkit/connector-gen`, `@bpmnkit/connectors`, `@bpmnkit/cli`.
- **Tools:** BPMN Kit for VS Code, Drop, `@bpmnkit/proxy` (the MCP server, `casen proxy mcp`),
  `@bpmnkit/markdown`, `@bpmnkit/camunda-docspack`, `@bpmnkit/patterns`,
  `@bpmnkit/worker-client`, `@bpmnkit/cli-sdk`, `@bpmnkit/create-casen-plugin`,
  `@bpmnkit/casen-report`, `@bpmnkit/casen-worker-http`, `@bpmnkit/casen-worker-ai`, and the
  shared plumbing `@bpmnkit/ui`, `@bpmnkit/profiles` and `@bpmnkit/astro-shared`.
- **Experimental:** Reebe, `@bpmnkit/reebe-wasm`, `@bpmnkit/operate`, `@bpmnkit/user-tasks`,
  `@bpmnkit/flow`, Studio, the Desktop app and proxy-rs.

Reebe is a dev/test engine: use it on your machine and in CI, not in production. The
`@bpmnkit/engine/wasm-runner` entry point is part of a Core package, so its API is covered,
but the Reebe engine it runs is Experimental and its behaviour can change in any release.

The tiers live in `TIER` and `APPS` in
[`scripts/published-packages.mjs`](https://github.com/bpmnkit/bpmnkit/blob/main/scripts/published-packages.mjs).
The repo's checks fail if a published package has no tier, if Core differs from the packages
at 1.0, or if an Experimental product reaches 1.0.

## Versions are per package, not per repo

Packages version independently. `@bpmnkit/core` reaching 2.0.0 does not make
`@bpmnkit/canvas` 2.0.0, and the two can sit many majors apart.

Sibling dependencies are declared as carets, so `@bpmnkit/plugins` depending on
`^1.2.0` of `@bpmnkit/core` resolves to one shared copy alongside your own `^1.4.0`.
Two copies of `@bpmnkit/core` in one tree is not a duplicate of one copy — class identity,
`instanceof` and module-level registries all stop matching across the seam — so keep BPMN Kit
packages within one major of each other.

Releases are cut by [Changesets](https://github.com/changesets/changesets). Every change that
reaches npm has a changeset naming its packages and its bump, and lands in that package's
`CHANGELOG.md`.

## What counts as public API

**The public API of a package is what its `exports` entry points export, minus anything
marked `@internal`.** Nothing else.

```ts
import { Bpmn } from "@bpmnkit/core"            // ✅ API
import { minimap } from "@bpmnkit/plugins/minimap" // ✅ API — a declared subpath
```

These are **not** API, and may change in any release:

| Not API | Why |
|---|---|
| Deep paths into `dist/` | An implementation layout, not an entry point |
| Members marked `/** @internal */` | Reachable from the `.d.ts` because TypeScript has no other way to say "not yours" — `ProcessBuilder` carries several |
| Anything reachable only by structural inference | If you cannot import it by name from an entry point, it is not named in the contract |
| `src/` in the repo | The published package is the artifact; the repository is not |

Each package's entry points are listed in its `exports` map. `@bpmnkit/plugins` is the one to
watch: it has **no root export**, only 34 subpaths, one per plugin.

**For a package whose product is a command**, `exports` says nothing — `@bpmnkit/cli` has none
at all. Its public API is instead its **documented commands**: the command and flag names, the
meaning of its exit codes, and the shape of any `--format json` output. Prose written to a
terminal for a human to read is not API, and neither is the exact wording of an error.

For a package that renders UI, the **rendered DOM and its class names are not API** either.
Style through the documented CSS custom properties; a panel's internal markup can change in a
minor.

## What is a breaking change

### Runtime behaviour

Breaking: removing or renaming an export or an entry point; removing a function parameter or
making an optional one required; throwing where a value used to be returned; changing a
documented default.

### Types

Type-level breakage is real breakage: a build that no longer compiles is a broken build. The
direction matters, and it is the opposite for things we hand you and things you hand us.

| Change | Verdict |
|---|---|
| Adding an export, or a new entry point | minor |
| Adding an **optional** property to an options object | minor |
| Adding a member to a union we **accept** | minor |
| Adding a member to a union we **return** | **major** — your exhaustive `switch` stops compiling |
| Adding a **required** property to anything you construct | **major** |
| Making a returned property optional | **major** — you now have to narrow it |
| Narrowing a return type | **major** |
| Widening a parameter type | minor |
| Renaming an exported type | **major**, even when the shape is identical |

### Generated BPMN, DMN and Form documents

This is the promise that matters most here, and the one a general semver policy has nothing
to say about. The rule is:

> **A change is breaking if it moves `semanticHash` for the same input. A change to the bytes
> alone is not.**

`semanticHash` is BPMN Kit's canonical, presentation-free projection of a model, and it is
exported for exactly this purpose. Verified against the current build:

| Property | Holds |
|---|---|
| The same input rebuilt produces the same hash | ✅ |
| `applyAutoLayout` does not move it | ✅ |
| Renaming an element moves it | ✅ |
| Changing an element **id** moves it | ✅ |

So, concretely:

- **Major** — different element ids, a changed document structure, a different default
  attribute on an emitted element, a changed FEEL expression. Anyone diffing generated files
  in review, or deploying them by id, sees these.
- **Minor or patch** — different layout coordinates, different attribute order, different
  whitespace, a nicer waypoint route. The picture moved; the model did not.

For the avoidance of doubt about precedent: `@bpmnkit/core` 0.4.0 derived element ids from the
model instead of generating them randomly. That moved `semanticHash` for every document, and
shipped as a *minor*. Under this policy it is a major, and 0.x is the only reason it was not.

### Formats outside the package

These are contracts even though no TypeScript signature describes them, and the same rule
applies — a change that makes an existing file, store or caller stop working is major:

- The **`.bpmn.tests.json` sidecar** read by `casen test` and the runner's Tests tab.
- **Profile storage on disk** — `~/.config/casen` on Linux, `~/Library/Application Support/casen`
  on macOS, `%APPDATA%\casen` on Windows. A format change must migrate existing profiles, not
  invalidate them.
- The **`@bpmnkit/proxy` HTTP surface**, for the routes the documentation names.
- **Element template validation** — a template that validates today does not start failing in
  a minor.

## What is not a breaking change

- Adding a feature, an export, an entry point, or an optional parameter.
- Fixing a bug so behaviour matches its documentation. If you relied on the bug, this can
  still move under you; it is a patch, and the changelog will say what changed.
- Performance, internal structure, dependency versions inside a compatible range.
- Anything about layout, formatting or diagram interchange that leaves `semanticHash` alone.
- Documentation, READMEs, or the contents of `@bpmnkit/docspack`.

## Runtime support

The supported runtimes are listed under
[Runtime Requirements](/docs/getting-started/installation#runtime-requirements): Node.js 20
LTS and newer, Deno 1.40+, Bun 1.0+, and browsers supporting ES2022. Every package is
**ESM-only** — there is no CommonJS build, and there will not be one.

Raising the floor follows the runtime's own lifecycle:

- Dropping a Node.js major that is **still in LTS** is a **major**.
- Dropping one that has reached **end of life** is a **minor**, called out in the release notes.
- Raising the browser baseline past ES2022 is a **major**.

## Deprecation

Nothing that is public API disappears without warning.

1. It is marked `@deprecated` in the type declarations, naming what to use instead. Your editor
   and your build show it; nothing breaks.
2. It keeps working for **at least one minor release**, and is listed in the changelog entry
   that deprecated it.
3. It is removed only in a major, and the major's release notes list every removal.

An alias kept purely for compatibility is documented as such — `ProcessBuilder`'s `strict`
option is the existing example, a deprecated alias for `explicitJoins`.

## Support window

Fixes land on the **latest minor of the current major**. When a new major ships, the previous
major gets security fixes for **six months**; other fixes require an upgrade.

Security issues should be reported through
[GitHub](https://github.com/bpmnkit/bpmnkit/issues) rather than in a public pull request.

## Which packages this covers

A package is covered by this page once it is at **1.0.0 or above**, and not before. The
distinction is deliberate: several packages are published, useful, and not yet ready to freeze
an API — shipping them as 1.0 to make the list tidy would be a promise the project could not
keep. Joining later costs nothing, because going from 0.x to 1.0 breaks no one, so the bar is
applied strictly rather than generously.

Three conditions, all of which must hold:

1. **A test suite that would catch its own breakage.**
2. **A documentation page** on this site.
3. **An API worth defending for a year.**

**Twelve packages** meet them today and carry the promise:

| | |
|---|---|
| [`@bpmnkit/core`](/docs/packages/core) | [`@bpmnkit/feel`](/docs/packages/feel) |
| [`@bpmnkit/canvas`](/docs/packages/canvas) | [`@bpmnkit/editor`](/docs/packages/editor) |
| [`@bpmnkit/engine`](/docs/packages/engine) | [`@bpmnkit/plugins`](/docs/packages/plugins) |
| [`@bpmnkit/api`](/docs/packages/api) | [`@bpmnkit/ascii`](/docs/packages/ascii) |
| [`@bpmnkit/connectors`](/docs/packages/connectors) | [`@bpmnkit/connector-gen`](/docs/packages/connector-gen) |
| [`@bpmnkit/docspack`](/docs/packages/docspack) | [`@bpmnkit/cli`](/docs/cli/casen) |

The other sixteen published packages stay on 0.x on purpose, and make no semver promise;
their [tier](#product-tiers) says what they do promise. Most are
short of the first two conditions; the rest are worked examples, scaffolders, or generated
builds with no API of their own to freeze.

The membership is not only prose. It lives in `STABLE` in
[`scripts/published-packages.mjs`](https://github.com/bpmnkit/bpmnkit/blob/main/scripts/published-packages.mjs),
and the repo's own checks enforce both directions of it: nothing on the list may lack tests or
a documentation page, and nothing at 1.0.0 or above may be missing from the list. A major
version cannot arrive by accident.

Whatever this page says, a package's current version on
[npm](https://www.npmjs.com/org/bpmnkit) is the authoritative answer.

---

### Conformance

What BPMN Kit implements of BPMN 2.0, DMN 1.3, FEEL and Camunda Forms — measured where a measurement exists, and with the gaps listed.

Source: https://bpmnkit.com/docs/getting-started/conformance

This page says how much of each standard BPMN Kit implements, and how that was checked. Where
there is a public test suite the number comes from it. Where there is not, the page lists what
is supported and what is missing, and links to the test that enforces it. Everything below
describes the current `main` branch.

## FEEL — 94.5% of the DMN TCK, 375 of 378 Camunda examples

`@bpmnkit/feel` passes **1,941 of the 2,053 FEEL test cases** in the
[DMN Technology Compatibility Kit](https://dmn-tck.github.io/tck/).

- The cases are extracted from a checkout of the TCK by
  `packages/feel/tasks/extract-tck-tests.mjs` and run by `packages/feel/tests/tck.test.ts`.
- The [DMN TCK workflow](https://github.com/bpmnkit/bpmnkit/actions/workflows/dmn-tck.yml)
  runs them against the latest TCK every Monday.
- The 112 cases that do not pass are listed in `KNOWN_FAILURES` in that test file, each with
  its reason. The run fails if a listed case starts passing, so the list cannot go stale.

The TCK's own [results table](https://dmn-tck.github.io/tck/) scores whole DMN engines across
every test, not only the FEEL cases. The figure above is not directly comparable with it, and
BPMN Kit has not submitted results.

**Camunda 8.** Zeebe evaluates FEEL with Camunda's own engine, which adds built-ins and
behaviour DMN does not define (`assert`, `partition`, `context put` with a key path, `to json`,
`fromAi`, …). There is no test suite for that dialect, so the measure is Camunda's
documentation: `@bpmnkit/feel` matches **375 of the 378 worked examples** in the FEEL pages of
the Camunda 8 docs.

- `packages/feel/tests/camunda-parity.test.ts` reads the examples from
  `@bpmnkit/camunda-docspack` at test time, evaluates each one, and compares the result with
  the documented one. It runs with the package's normal tests.
- Examples that cannot run standalone — signatures, results written in prose, anything that
  reads the clock — are skipped. `node packages/feel/tasks/extract-camunda-examples.mjs
  --skipped` lists each one with its reason.
- The three that differ are in `KNOWN_DIFFERENCES` in that file, and on the
  [FEEL page](/docs/packages/feel#camunda-parity): `round up` without a scale (twice), and
  moving a date and time without a zone into another zone.
- Camunda fails an evaluation that errors. This package returns `null`, as DMN specifies.

## BPMN 2.0 — model and round trip

`@bpmnkit/core` parses and writes BPMN 2.0 XML. Coverage is measured against the BPMN, BPMN DI
and Zeebe moddle descriptors vendored into the repository, which list every type the
standard and Camunda 8 define (151 in total):

| Status | Types | Meaning |
|---|---|---|
| Modelled | 109 | Parsed into typed objects and written back |
| Preserved | 34 | Not modelled, but kept verbatim on round trip |
| Dropped | 6 | Lost on round trip — see below |
| Unprobed | 2 | Not reachable from `bpmn:definitions` |

The dropped types are the data-association internals (`Assignment`, `DataAssociation`,
`FormalExpression` inside one, `DataState`, `ItemAwareElement`) and `ImplicitThrowEvent`. The
`packages/core/tests/descriptor-coverage.test.ts` gate fails the build if a new type would be
dropped silently; `pnpm --filter @bpmnkit/core check:descriptors` prints the full report.

[Round-trip fidelity](/docs/getting-started/concepts#round-trip-fidelity) lists the
deliberate normalisations and the children that are still not preserved.

## BPMN Model Interchange (MIWG)

The [OMG BPMN Model Interchange Working Group test suite](https://github.com/bpmn-miwg/bpmn-miwg-test-suite)
is how BPMN tools show they can read and write each other's files. Its reference models
cover layout (`A.*`), the descriptive and analytic conformance classes (`B.*`) and complex
real-world scenarios (`C.*`). They were exported by Trisotech, Signavio, W4, BOC, itp commerce
and others, so they carry each vendor's namespaces, label styles and optional attributes.

All 22 reference models are part of the round-trip corpus (suite commit `2ff82d4`,
2026-09-21) and are checked on every build:

| Check | Result |
|---|---|
| Import (parse) | 22 / 22 |
| Export re-imports to the same model | 22 / 22 |
| Export is a fixed point (a second round trip changes nothing) | 22 / 22 |
| Semantic content preserved | 22 / 22 |
| Diagram interchange preserved (bounds, waypoints, label styles, vendor DI attributes) | 22 / 22 |
| `exportPreserving` of an unchanged model is byte-identical | 22 / 22 |

What a plain export changes is listed per model in `ALLOWED` in
`packages/core/tests/roundtrip-corpus.test.ts`:
- `false` defaults such as `isForCompensation="false"` are not written back;
- an empty `<extensionElements/>` is not written back.

Neither loses content. The comparison is keyed by namespace, so
`<process>`, `<semantic:process>` and `<bpmn:process>` count as the same element.

Running the suite found seven models BPMN Kit could not open and several losses, all fixed
before these results were recorded:
- DI elements without the optional `id` or `bpmnElement` would not parse;
- a document with BPMN as its default namespace was written back as invalid XML;
- a default flow on an activity was dropped;
- so were documentation on sequence flows, the name of `<definitions>` and of a
  collaboration, and empty timer and condition expressions;
- extensions on data associations and label styles were lost;
- so were the `id` and `textFormat` attributes of `<documentation>`.

The results are BPMN Kit's own run of the suite's models, not a submission to the MIWG, which
publishes vendor-submitted results separately.

## BPMN elements by component

| Elements | Model | Renderer (`canvas`) | Editor palette | TS simulator (`engine`) |
|---|---|---|---|---|
| Service, user, script, business rule tasks | ✓ | ✓ | ✓ | Executed |
| Send, receive, manual and plain tasks | ✓ | ✓ | ✓ | Pass through |
| Exclusive, parallel, inclusive gateways | ✓ | ✓ | ✓ | Executed; inclusive joins do not wait |
| Event-based, complex gateways | ✓ | ✓ | ✓ | Event-based executed; complex splits like inclusive, without its activation condition |
| Embedded sub-process, transaction | ✓ | ✓ | ✓ | Executed (child scope); no transaction cancel events |
| Event sub-process, ad-hoc sub-process, call activity | ✓ | ✓ | ✓ | Event sub-process executed; call activity executed when the called process is deployed in the same engine; ad-hoc sub-process with a job worker executed (job results activate its tools), without one it passes through |
| Start / end: none, terminate, error | ✓ | ✓ | ✓ | Executed |
| Timer and message catch events | ✓ | ✓ | ✓ | Executed |
| Timer (interrupting) and error boundary events | ✓ | ✓ | ✓ | Executed, including errors thrown by job workers |
| Signal, escalation, compensation, conditional, link events | ✓ | ✓ | ✓ | Executed, except conditional events (not evaluated) |
| Message and non-interrupting boundary events | ✓ | ✓ | ✓ | Executed (timer, message, signal, escalation) |
| Multi-instance and loop markers | ✓ | ✓ | Properties panel | Multi-instance executed |
| Data objects, data stores, associations | ✓ | ✓ | — | — |
| Groups, text annotations | ✓ | ✓ | ✓ | — |
| Pools, lanes, message flows | ✓ | ✓ | ✓ | — |
| Choreography and conversation diagrams | — | — | — | — |

The TypeScript simulator is for tests, demos and step-through debugging. It follows Zeebe's
rules where it implements an element — error and escalation propagation through scopes and
call activities, variable propagation and mappings, multi-instance variables and completion
conditions — and `packages/engine/tests/semantics.test.ts` checks each one. It is not checked
against Zeebe itself, and it differs in the places the table notes: a call activity can only
call a process deployed in the same `Engine`, and it runs compensation handlers one at a time
in reverse order, as BPMN specifies, where Zeebe starts them all at once. For Zeebe semantics,
`@bpmnkit/engine/wasm-runner` runs the same scenarios on **Reebe** compiled to WebAssembly.
Reebe's model covers the task types, call activities, embedded and event sub-processes,
exclusive, parallel, inclusive and event-based gateways, catch, throw and boundary events
(timer, message, signal, error, escalation, terminate, link, compensation) and
multi-instance. Errors and escalations, from end events, throw events and job workers,
propagate out through sub-processes and call activities to a boundary event or an event
sub-process, which receives the variables a job worker threw the error with. An uncaught
error raises an incident. An exclusive gateway with no matching condition and no default
flow raises an incident, as does an inclusive split, and resolving it evaluates the gateway
again; resolving any incident raised while an element was activating retries that element
instance. A gateway condition that does not evaluate to a boolean (a missing variable is
`null`) raises an `EXTRACT_VALUE_ERROR` incident instead of counting as false, and resolving
it evaluates the gateway again. Parallel gateways, and every element other than an exclusive
or inclusive gateway, ignore conditions on their outgoing flows, as Zeebe does. A link throw
event continues at the link catch event of its name in the same scope, and deployment rejects
links that do not pair up. A compensation throw or end event starts, all at once, the
handlers of the activities that completed in its scope and in the completed sub-processes
inside it (or only `activityRef`), and waits for them; a throw event in an event
sub-process compensates the event sub-process and the scope around it. Every handler runs in
the throw event's scope, as in Zeebe, and, as in Zeebe, only a handler that completes releases
the throw event: one terminated on its own leaves it waiting. Timer, message and signal boundary events are armed when their activity starts and cancelled when it ends. An interrupting one
terminates the activity; a non-interrupting one leaves it running, and a timer cycle repeats.
An event-based gateway waits for the first of its events and cancels the others.
The timer, message and signal start events of event sub-processes are armed when their
process or sub-process starts and disarmed when it ends. An interrupting event sub-process
terminates the rest of its scope and triggers once; a non-interrupting one runs alongside,
as often as its event occurs. An inclusive gateway takes every flow whose condition holds,
or its default flow, and its join waits until no token in the scope can still reach an
incoming flow that has none. A token waiting at a parallel or inclusive join keeps its
scope active, as in Zeebe, even if the join can never fire.
Deploying a process schedules its timer start events (a date, a repeating interval or a cron
expression) and subscribes its message start events; a timer firing or a matching message
creates an instance, at most one active instance per message correlation key, and a new version
replaces the previous version's timers and subscriptions. A sub-process or process instance
completes only when nothing inside it is active any more, and a terminate end event ends the
rest of its own scope and completes that scope.
Multi-instance runs, in parallel or in sequence, on every task type, sub-process and call
activity. Each instance has its own `inputElement` and `loopCounter`, the output is collected
in input order, and a `completionCondition` ends the loop early. A multi-instance or ad-hoc
`completionCondition` that does not evaluate to a boolean raises an `EXTRACT_VALUE_ERROR`
incident, with Zeebe's message, on the instance that was completing (for an ad-hoc
sub-process, the activation or the event sub-process inside it that was completing);
resolving it evaluates the condition again. An ad-hoc `completionCondition` is evaluated in
the ad-hoc sub-process's own scope, as in Zeebe. Undefined and manual tasks pass through, and a flow element written as an
empty tag (`<bpmn:userTask id="x"/>`) is read like one with children. A complex gateway fails
deployment, as in Zeebe, which does not execute it. An ad-hoc sub-process activates its
inner elements, each in its own activation, from `activeElementsCollection` or from the job
result of its job worker implementation (such as the AI Agent Sub-process), completes by
its `completionCondition` or the job result, and creates the job again after each
activation. It creates the `adHocSubProcessElements` variable with the elements it can
activate and their `fromAi()` parameters in Zeebe's shape: a parameter is named by its whole
reference (`toolCall.orderId`), a `fromAi()` call on any reference is listed, and a field that
is null or empty is left out. The TypeScript engine gives the same shape, and a test checks
that the two agree. A `fromAi()` call that Zeebe rejects at deployment (a value that is not a
reference, a description or type that is not a string literal, a schema or options that is
not a context of literals, `null` included) fails the deployment with Zeebe's message, on
Reebe and in the TypeScript engine. The gRPC calls pass their `variables` documents on as
variables and reject a document that is not a JSON object, as Zeebe's gateway does, and
Reebe's REST API can activate elements of an active one
(`POST /v2/element-instances/ad-hoc-activities/{key}/activation`). Process instance
modification (REST `POST /v2/process-instances/{key}/modification` and gRPC
`ModifyProcessInstance`) activates elements, with ancestor selection and variables,
terminates element instances and moves them, with Zeebe's rules and rejection messages.
A redeployed DMN gets a new version when its content changes and keeps its version when it
does not, and a decision evaluates by its id (the latest version) or by its key. Every
scenario of the [template gallery](/docs/guides/templates) passes on it.

Reebe is a dev/test engine in the
[Experimental tier](/docs/getting-started/stability#product-tiers), not for production. It is
a clean-room implementation of the Zeebe API written from Camunda's public documentation, it
is not affiliated with Camunda, and its behaviour is checked by its own tests rather than
against Zeebe. "Zeebe" and "Camunda" are trademarks of Camunda Services GmbH.

## Zeebe extensions

Every `zeebe:` element in the vendored Zeebe descriptor is modelled or preserved, and 26 of
them are checked for placement — which BPMN element each may appear on — by
`packages/core/src/bpmn/zeebe-placement.ts`. That includes task definitions, IO mappings,
task headers, called decisions and elements, forms, user tasks, scripts, linked resources,
ad-hoc sub-process and AI agent settings, version tags, and execution and task listeners.

[Element templates](/docs/packages/connectors) (Camunda's connector template JSON) are applied
for outbound and inbound connectors. `applyTemplateToElement` writes the inbound bindings to
the element's message and its `zeebe:subscription` correlation key, where Camunda reads them,
and applies `zeebe:linkedResource` bindings.

Camunda 7 (`camunda:` extensions) is not modelled: those attributes and elements are kept on
round trip, including those on multi-instance loops and event definitions.
`convertCamunda7()` / `casen migrate c7` convert
Camunda 7 models to Camunda 8 and report what needs manual work. See
[Migrate from Camunda 7](/docs/guides/migrate-from-camunda-7).

## Linting — bpmnlint compatibility

`casen lint` and the VS Code extension read a project's `.bpmnlintrc`. All 28 of bpmnlint's
built-in rules map onto BPMN Kit findings exactly, in the top-level process and inside every
kind of sub-process. When the project has bpmnlint installed, that bpmnlint runs the
configuration itself, so `bpmnlint-plugin-*` rules work too.
[bpmnlint Compatibility](/docs/guides/bpmnlint) has the rule-by-rule table. On the 43 `.bpmn`
files in this repository under `bpmnlint:all`, the MIWG models included, every rule reports the
same elements as bpmnlint. A test checks this on every run.

## DMN 1.3

- Decision tables with all seven hit policies (`UNIQUE`, `FIRST`, `ANY`, `COLLECT`,
  `RULE ORDER`, `OUTPUT ORDER`, `PRIORITY`) and the `COLLECT` aggregations (`SUM`, `MIN`,
  `MAX`, `COUNT`).
- Decision requirements graphs: input data, business knowledge models, knowledge sources, and
  information, knowledge and authority requirements, with DMNDI layout.
- Input and output `typeRef` is limited to `string`, `boolean`, `number` and `date`.
- Not modelled: literal-expression decisions and the boxed expressions of DMN 1.3
  (context, relation, list, invocation, function definition).

## Camunda Forms

Camunda form JSON at schema version 16, with 22 component types: text, text field, text area,
number, date/time, select, radio, checkbox, checklist, tag list, group, dynamic list, table,
image, document preview, iframe, HTML, expression, file picker, button, separator and spacer.

## Known gaps, in one list

- Choreography and conversation diagrams
- Camunda 7 extensions (preserved, not modelled; `casen migrate c7` converts them to Camunda 8)
- DMN boxed expressions and literal-expression decisions
- TS simulator: conditional events, message start events of a top-level process, transaction
  cancel events, compensation event sub-processes, inclusive and complex joins (they do not
  wait), complex gateway activation conditions, and inner activities of ad-hoc sub-processes
  without a job worker (`activeElementsCollection` is not evaluated)
- Reebe: a decision evaluation reports no `evaluatedDecisions` (matched rules and inputs);
  a redeployed BPMN process always gets a new version, even when it has not changed;
  single-node only, no published comparison with Zeebe, and no published performance figures

Found something this page gets wrong? [Open an issue](https://github.com/bpmnkit/bpmnkit/issues).

---

## Documentation — Guides

### Building Processes

Service tasks, user tasks, events, sub-processes, boundary events, multi-process diagrams, and multi-instance patterns.

Source: https://bpmnkit.com/docs/guides/building-processes

## Service Tasks

A service task represents work done by a system. In Camunda 8 / Zeebe, a job worker picks up
the task and completes it:

```typescript
.serviceTask("charge-card", {
  name: "Charge Credit Card",
  taskType: "payment-charge",       // worker subscribes to this type
  taskHeaders: {
    retries: "3",
  },
  inputMappings: [
    { source: "= amount", target: "chargeAmount" },
    { source: "= card.token", target: "token" },
  ],
  outputMappings: [
    { source: "= transactionId", target: "paymentTransactionId" },
  ],
})
```

## User Tasks

A user task waits for a human actor. Optionally attach a Camunda form:

```typescript
.userTask("review-order", {
  name: "Review Order",
  assignee: "= initiator",           // FEEL expression
  candidateGroups: "approvers",
  formKey: "camunda-forms:bpmn:review-form",
  dueDate: "= now() + duration(\"P2D\")",
})
```

## Events

### Start Events

```typescript
// None start
.startEvent("start")

// Timer start (runs on a schedule)
.startEvent("start-daily", {
  timer: { timeCycle: "R/PT24H" },   // ISO 8601 repeating interval
})

// Message start
.startEvent("start-on-order", {
  message: { name: "order-received", correlationKey: "= orderId" },
})
```

### Intermediate Events

```typescript
// Catch a timer (delay)
.intermediateCatchEvent("wait-1h", {
  timer: { timeDuration: "PT1H" },
})

// Catch a message (wait for external signal)
.intermediateCatchEvent("wait-for-payment", {
  message: { name: "payment-confirmed", correlationKey: "= orderId" },
})

// Throw a message
.intermediateThrowEvent("notify-warehouse", {
  message: { name: "order-ready" },
})
```

Link events are a "go-to" inside one process or sub-process: a link throw continues at the link
catch with the same name. The throw has no outgoing flow and the catch no incoming one, so the
builder stops chaining at the throw and starts a new chain at the catch:

```typescript
.serviceTask("check", { name: "Check", taskType: "check" })
.intermediateThrowEvent("to-retry", { linkName: "Retry" })    // nothing chains from here
.intermediateCatchEvent("from-retry", { linkName: "Retry" })  // starts a new chain
.serviceTask("retry", { name: "Retry", taskType: "retry" })
```

### End Events

```typescript
// Normal end
.endEvent("end")

// Error end (triggers error boundary event)
.endEvent("end-error", {
  error: { code: "PAYMENT_FAILED", message: "Payment processing failed" },
})

// Message end
.endEvent("end-notify", {
  message: { name: "process-complete" },
})
```

## Sub-Processes

Embed a child process inline. Sub-processes support the full builder API including
gateways and branching:

```typescript
.subProcess("handle-payment", (sub) =>
  sub
    .startEvent("sub-start")
    .serviceTask("charge", { taskType: "payment-charge" })
    .exclusiveGateway("charge-ok?")
    .branch("success", (b) =>
      b.condition("= success").serviceTask("receipt", { taskType: "send-receipt" }).endEvent("sub-end")
    )
    .branch("failure", (b) =>
      b.defaultFlow().endEvent("sub-failed", { error: { code: "CHARGE_FAILED" } })
    )
)
```

### Event Sub-Processes

An event sub-process starts when a boundary event fires:

```typescript
.eventSubProcess("compensation", {
  triggeredByEvent: true,
  startEvent: {
    interrupting: false,
    error: { code: "PAYMENT_FAILED" },
  },
}, (sub) =>
  sub
    .serviceTask("refund", { taskType: "issue-refund" })
    .endEvent("refunded")
)
```

## Boundary Events

### `.withBoundary()` — recommended

`.withBoundary()` attaches a boundary event to the preceding task, lets you build the
error/timeout path inline, then **automatically restores the cursor to the original task**
so the main flow continues naturally:

```typescript
.serviceTask("charge", { name: "Charge Card", taskType: "payment-charge" })
.withBoundary("on-fail", { errorCode: "PAYMENT_FAILED", cancelActivity: true }, (p) =>
  p
    .serviceTask("notify", { taskType: "send-email" })
    .endEvent("end-failed"),
)
// cursor is back on "charge" — main flow continues here
.serviceTask("fulfill", { name: "Fulfill Order", taskType: "warehouse-pick" })
.endEvent("end-ok")
```

Timer boundaries work the same way:

```typescript
.serviceTask("slow-task", { taskType: "long-job" })
.withBoundary("on-timeout", { timerDuration: "PT30S", cancelActivity: false }, (p) =>
  p.serviceTask("escalate", { taskType: "alert" }).endEvent("escalated"),
)
.serviceTask("next-task", { taskType: "continue" })
```

### `.boundaryEvent()` — lower-level

Use `.boundaryEvent()` directly when you need precise cursor control. It moves the
builder cursor to the boundary event itself:

```typescript
.serviceTask("process-order", { taskType: "order-processor" })
.boundaryEvent("timeout", {
  attachedTo: "process-order",
  cancelActivity: true,
  timer: { timeDuration: "PT30M" },
})
.endEvent("timed-out")
```

## Call Activities

Invoke a separate (reusable) process definition:

```typescript
.callActivity("run-subprocess", {
  name: "Run Fulfillment Sub-Process",
  calledElement: "fulfillment-process",
  propagateAllChildVariables: false,
  inputMappings: [
    { source: "= orderId", target: "orderId" },
  ],
  outputMappings: [
    { source: "= trackingNumber", target: "trackingNumber" },
  ],
})
```

## Multi-Process Diagrams

`Bpmn.createDiagram()` assembles multiple processes into a single definitions document.
This is useful for caller/callee pairs or any workflow that references another process:

```typescript
import { Bpmn } from "@bpmnkit/core";

const defs = Bpmn.createDiagram("OrderSystem")
  .process("order-flow", (p) =>
    p
      .startEvent("start")
      .callActivity("run-payment", { processId: "payment-flow" })
      .endEvent("end"),
  )
  .process("payment-flow", (p) =>
    p
      .startEvent("s")
      .serviceTask("charge", { name: "Charge", taskType: "payment-charge" })
      .endEvent("e"),
  )
  .build();

const xml = Bpmn.export(defs); // both processes in one XML file
```

## Task Defaults

`.defaults()` sets process-wide defaults applied to all subsequent task calls.
Useful when every service task in a process should share the same retry policy:

```typescript
Bpmn.createProcess("my-flow")
  .defaults({ serviceTask: { retries: "5" } })
  .startEvent("s")
  .serviceTask("t1", { name: "Task 1", taskType: "worker-a" })  // retries: "5"
  .serviceTask("t2", { name: "Task 2", taskType: "worker-b" })  // retries: "5"
  .serviceTask("t3", { name: "Task 3", taskType: "worker-c", retries: "1" })  // override
  .endEvent("e")
  .build()
```

## Multi-Instance

Run a task or sub-process once per item in a collection:

```typescript
.serviceTask("notify-all", {
  name: "Notify Each Customer",
  taskType: "send-email",
  multiInstance: {
    parallel: true,                          // false = sequential
    inputCollection: "= customers",
    inputElement: "customer",
    outputCollection: "results",
    outputElement: "= { sent: true, email: customer.email }",
  },
})
```

## Generated IDs

You name every flow node. The builder names everything else, and it derives those names from
the model so that rebuilding an unchanged process produces unchanged BPMN — a diff that shows
only what you actually changed.

A sequence flow is named after the two elements it connects:

```typescript
Bpmn.createProcess("orders")
  .startEvent("start")
  .serviceTask("validate", { taskType: "validate" })
  .endEvent("done")
  .build()
// Flow_start_validate, Flow_validate_done
```

When several flows connect the same pair — the branches of a gateway converging on one join —
each gets a discriminator taken from the branch name, or from its condition when the branch is
unnamed:

```typescript
.exclusiveGateway("gw")
.branch("approved", (b) => b.connectTo("done"))
.branch("rejected", (b) => b.connectTo("done"))
// Flow_gw_gw_join_approved, Flow_gw_gw_join_rejected
```

Because the id comes from the connection rather than from a counter, adding or reordering an
unrelated element leaves the other flows' ids alone. The same is true of root definitions
created from event options — `Message_Order_Received` for `messageName: "Order Received"`, and
likewise `Error_`, `Signal_` and `Escalation_` from the code or name they carry.

Two consequences worth knowing:

- **Ids are only as stable as the elements they name.** Omitting an element id (`.startEvent()`
  with no argument) gets you a generated one that changes on every build, and the flow ids
  around it inherit that. Name the nodes you care about.
- **`defaultFlow` becomes predictable.** Setting a gateway's default by id no longer requires
  knowing a random value: `{ defaultFlow: "Flow_gw_gw_join_rejected" }`. `.branch().defaultFlow()`
  is still the shorter way to say it.

`continueProcess()` never renumbers what the document arrived with: flows the builder did not
create keep their ids, and new ones avoid them.

### Naming a root definition yourself

When the id of a message, error, signal or escalation matters — because a message flow in another
pool, a worker, or a deployed process already refers to it — declare it before the events that
use it:

```typescript
Bpmn.createProcess("orders")
  .message("Msg_OrderReceived", { name: "Order Received" })
  .error("Err_OutOfStock", { code: "OUT_OF_STOCK", name: "Out of stock" })
  .signal("Sig_Cancelled", { name: "Order Cancelled" })
  .escalation("Esc_Review", { code: "NEEDS_REVIEW" })
  .startEvent("start", { messageName: "Order Received" })   // messageRef: Msg_OrderReceived
```

Events still name these by name or code, exactly as before — the declaration only decides the id
they resolve to. Order matters: an event built first declares the definition itself, and
declaring it afterwards under a different id throws rather than leaving two definitions of one
message behind.

---

### Gateways & Branching

Exclusive, parallel, inclusive, and event-based gateways with condition expressions.

Source: https://bpmnkit.com/docs/guides/gateways

## Exclusive Gateway (XOR)

Only one outgoing path is taken — the first branch whose condition evaluates to `true`.
One branch should always be the default to handle the fallthrough case:

```typescript
import { Bpmn } from "@bpmnkit/core";

const xml = Bpmn.export(
  Bpmn.createProcess("approval-flow")
    .startEvent("start", { name: "Request Submitted" })
    .userTask("review", { name: "Review Request" })
    .exclusiveGateway("approved?", { name: "Approved?" })
    .branch("yes", (b) =>
      b.condition("= approved")
        .serviceTask("notify", { taskType: "send-email", name: "Send Approval" })
        .endEvent("done")
    )
    .branch("no", (b) =>
      b.defaultFlow()
        .endEvent("rejected", { name: "Request Rejected" })
    )
    .withAutoLayout()
    .build()
);
```

### Conditions

Branch conditions are [FEEL expressions](https://docs.camunda.io/docs/components/modeler/feel/):

```typescript
.branch("high-value", (b) =>
  b.condition("= amount > 10000")
    .serviceTask("manual-review", { taskType: "escalate" })
    .endEvent("escalated")
)
```

## Parallel Gateway (AND)

All outgoing paths run concurrently. A matching parallel join gateway waits for all paths
to complete before continuing:

```typescript
const xml = Bpmn.export(
  Bpmn.createProcess("order-fulfillment")
    .startEvent("start")
    .parallelGateway("split")
    .branch("warehouse", (b) =>
      b.serviceTask("pick", { taskType: "warehouse-pick", name: "Pick Items" })
    )
    .branch("payment", (b) =>
      b.serviceTask("charge", { taskType: "payment-charge", name: "Charge Card" })
    )
    .parallelGateway("join")   // waits for all branches
    .serviceTask("ship", { taskType: "shipping", name: "Ship Order" })
    .endEvent("end")
    .withAutoLayout()
    .build()
);
```

## Inclusive Gateway (OR)

One or more outgoing paths are taken based on conditions. All active paths converge at the
matching inclusive join:

```typescript
.inclusiveGateway("options")
.branch("express", (b) =>
  b.condition("= expressShipping").serviceTask("fedex", { taskType: "fedex-ship" })
)
.branch("gift-wrap", (b) =>
  b.condition("= giftWrap").serviceTask("wrap", { taskType: "wrap-items" })
)
.branch("standard", (b) =>
  b.defaultFlow().serviceTask("standard-ship", { taskType: "usps-ship" })
)
.inclusiveGateway("join")
.endEvent("end")
```

## Event-Based Gateway

Waits for the _first_ of several events to occur, then takes that path:

```typescript
.eventBasedGateway("wait-for-event")
.branch("payment", (b) =>
  b.intermediateCatchEvent("payment-received", {
    message: { name: "payment-confirmed", correlationKey: "= orderId" },
  })
  .endEvent("paid")
)
.branch("timeout", (b) =>
  b.intermediateCatchEvent("payment-timeout", {
    timer: { timeDuration: "PT24H" },
  })
  .endEvent("cancelled")
)
```

## Branching Inside Sub-Processes

The full gateway and branching API works inside `subProcess()` callbacks too:

```typescript
.subProcess("handle-request", (sub) =>
  sub
    .startEvent("s")
    .exclusiveGateway("route")
    .branch("fast-path", (b) =>
      b.condition("= priority == \"high\"")
        .serviceTask("express", { taskType: "express-handler" })
        .endEvent("done-fast"),
    )
    .branch("normal", (b) =>
      b.defaultFlow()
        .serviceTask("standard", { taskType: "standard-handler" })
        .endEvent("done-normal"),
    )
)
```

Auto-join gateway insertion applies inside sub-processes the same way it does at the
top level — converging branches automatically get a matching join gateway.

## Nested Branching

Branches can contain further gateways:

```typescript
.exclusiveGateway("route")
.branch("enterprise", (b) =>
  b.condition("= tier == \"enterprise\"")
    .parallelGateway("enterprise-split")
    .branch("account-mgr", (b2) =>
      b2.userTask("assign-am", { name: "Assign Account Manager" })
    )
    .branch("onboarding", (b2) =>
      b2.serviceTask("kick-off", { taskType: "onboarding-kit" })
    )
    .parallelGateway("enterprise-join")
    .endEvent("enterprise-done")
)
.branch("self-serve", (b) =>
  b.defaultFlow()
    .serviceTask("auto-setup", { taskType: "self-serve-setup" })
    .endEvent("self-serve-done")
)
```

---

### Pattern Library

Domain BPMN patterns that Claude uses as context when implementing processes with /bpmnkit:implement.

Source: https://bpmnkit.com/docs/guides/patterns

The pattern library (`@bpmnkit/patterns`) provides domain knowledge for common business
processes. When you run `/bpmnkit:implement`, Claude checks the library for a matching
pattern (`casen pattern list`/`get`) and uses its readme and worker specs as context while
writing the `ProcessPlan` — the pattern's own `template` field predates the plan/synth
pipeline and is a rough structural reference, not something pasted in directly.

Patterns are hints, not templates. Claude adapts them to the specific request and ignores
them entirely when nothing relevant matches.

## Available patterns

| Pattern ID | Domain | Typical use |
|---|---|---|
| `invoice-approval` | Finance / accounts payable | Multi-level invoice review and ERP payment trigger |
| `employee-onboarding` | HR | Account provisioning, orientation scheduling, system access |
| `supplier-contract-review` | Procurement / legal | Contract classification, risk scan, CLM storage, e-signature |
| `incident-response` | IT / ops | Severity classification, on-call paging, post-mortem creation |
| `loan-origination` | Financial services | Identity verification, credit check, risk scoring, disbursement |
| `content-moderation` | Trust & safety | AI scan, action enforcement, CSAM reporting, user notification |
| `order-fulfillment` | E-commerce / supply chain | Inventory validation, payment, warehouse order, shipment tracking |

## How matching works

`casen pattern get <query>` (via `findPattern()`) scores each pattern by counting how
many of its keywords appear in the request. The highest-scoring pattern is selected.
Exact pattern ID matches take priority over keyword scoring.

Examples:

| Request | Matched pattern |
|---|---|
| "invoice approval workflow" | `invoice-approval` |
| "employee onboarding with Okta and Jira" | `employee-onboarding` |
| "on-call incident escalation" | `incident-response` |
| "custom blockchain process" | _(no match — Claude works from scratch)_ |

## What a pattern contains

Each pattern has four components:

**README** — domain context, common variations, relevant regulations, and conventions.
Claude reads this before generating the BPMN.

**Template** — a compact BPMN template in the BPMNKit intermediate format (not raw XML).
Used as a starting-point structure, not a fixed output.

**Worker specs** — typical service tasks with job type, inputs, outputs, and real integration
options (e.g. "SAP, NetSuite, or QuickBooks" for a payment trigger).

**Variations** — common process variants (e.g. "3-way match", "auto-approve below threshold")
so Claude can adapt the flow to the user's specific context.

## Using patterns from the CLI

```sh
casen pattern list
casen pattern get invoice-approval
casen pattern get "employee onboarding workflow"   # free-text match
```

## Patterns and templates

The same package has a second export, `@bpmnkit/patterns/templates`. It holds the
[runnable process templates](/docs/guides/templates) behind the [gallery](/templates):
complete, deployable processes with test scenarios. A pattern gives an AI model context to
write its own process. A template is a finished process you copy and change. Use
`casen pattern` for patterns and `casen template` for templates.

## Using patterns from code

You can access the pattern library directly in TypeScript:

```typescript
import { ALL_PATTERNS, findPattern } from "@bpmnkit/patterns"

// List all patterns
console.log(ALL_PATTERNS.map((p) => p.id))

// Find by keyword match
const pattern = findPattern("employee onboarding workflow")
console.log(pattern?.id)  // "employee-onboarding"

// Find by exact ID
const invoice = findPattern("invoice-approval")
console.log(invoice?.workers.map((w) => w.jobType))
```

## Pattern schema

```typescript
interface Pattern {
  id: string
  name: string
  description: string
  keywords: string[]
  readme: string                // domain context, Markdown
  workers: WorkerSpec[]
  variations: string            // common customizations, Markdown
  template: PatternTemplate     // compact BPMN structure — a rough reference, predates ProcessPlan
}

interface WorkerSpec {
  name: string
  jobType: string
  description: string
  inputs: Record<string, string>
  outputs: Record<string, string>
  externalApis?: string[]  // e.g. ["Stripe", "Adyen", "Braintree"]
  optional?: boolean
}
```

## Adding custom patterns

Create a new pattern file in `packages/patterns/src/patterns/` and export it from `index.ts`.
Follow the existing patterns as a reference — each is a single TypeScript file that exports
a `Pattern` object.

For private or organisation-specific patterns, add them to your project and contribute the
pattern object to `ALL_PATTERNS` via the `findPattern` API. Contributions to the seed library
are welcome via pull request.

## See also

- [Building Processes with AI](/docs/guides/ai-implement) — how Claude uses patterns during `/bpmnkit:implement`
- [`@bpmnkit/patterns` source](https://github.com/bpmnkit/bpmnkit/tree/main/packages/patterns)

---

### Process Templates

25 runnable Camunda 8 process templates — business processes and AI agent patterns — with test scenarios, from the gallery, the editor or casen template use.

Source: https://bpmnkit.com/docs/guides/templates

The [template gallery](/templates) holds 25 Camunda 8 processes you can start from. Each one
is built with the `@bpmnkit/core` builder and laid out automatically. Job types, IO mappings,
correlation keys, timers and error codes are already set. It lints with no errors, and it
comes with test scenarios: a happy path and at least one alternative path.

The templates live in `@bpmnkit/patterns/templates`. The package's tests build every
template, lint it, round-trip it through XML and run each scenario on `@bpmnkit/engine`.
A template that stops passing fails the build.

## What is in the gallery

| Category | Templates |
|---|---|
| Order to cash | `order-to-cash`, `payment-collection` |
| Approvals | `purchase-request-approval`, `expense-approval`, `contract-approval` |
| Onboarding | `employee-onboarding`, `customer-kyc-onboarding` |
| Incident & escalation | `incident-escalation`, `security-alert-triage` |
| Document processing | `invoice-capture`, `document-signature`, `document-classification` |
| SLA & timers | `support-ticket-sla`, `scheduled-report` |
| Sagas & error handling | `travel-booking-saga`, `payment-saga` |
| Human in the loop | `four-eyes-review`, `content-review` |
| AI agent patterns | `ai-prompt-chaining`, `ai-routing`, `ai-parallelization`, `ai-orchestrator-workers`, `ai-evaluator-optimizer`, `ai-human-approval-gate`, `ai-agent-tool-loop` |

The AI agent patterns follow Anthropic's
[Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
taxonomy. Each fixed step is one model call through Camunda's **AI Agent Task** connector
(`io.camunda.agenticai:aiagent:1`). The orchestrator–workers and tool-loop templates use the
**AI Agent Sub-process** connector (`io.camunda.agenticai:aiagent-job-worker:1`). That connector
is an ad-hoc sub-process whose tools are the activities inside it. The model decides which
tools to call and when.

## Use a template

Pick one of three ways from a template's page:

- **Open in editor** opens the diagram in the [browser editor](/editor). The link is
  `/editor?template=<id>`, and it only accepts a template id from the gallery.
- **Download .bpmn** saves the process model. The page also links the scenarios file and any
  DMN or form files.
- **`casen template use`** writes all the files into your project:

```sh
casen template list                          # all templates
casen template list --category ai-agents     # one category
casen template use purchase-request-approval processes/
```

```text
✓ Wrote processes/purchase-request-approval.bpmn
✓ Wrote processes/purchase-request-approval.bpmn.tests.json
✓ Wrote processes/approval-matrix.dmn
```

`casen template use` does not overwrite a file that already exists. Pass `--force` to
overwrite it. Then deploy each file with `casen deploy deploy <file> --target camunda8`, or
deploy them from the editor.

## Run the scenarios

The `.bpmn.tests.json` file has the scenario format that `runScenario` in
`@bpmnkit/engine` reads. Each scenario sets the start variables and the mocked job workers,
keyed by job type. Native user tasks are keyed `userTask`. The scenario also sets the element
path and the variables to expect. To run them in a Vitest or Node test:

```typescript
import { readFileSync } from "node:fs"
import { Bpmn, Dmn } from "@bpmnkit/core"
import { Engine, runScenario } from "@bpmnkit/engine"
import type { ProcessScenario } from "@bpmnkit/engine"

const defs = Bpmn.parse(readFileSync("processes/purchase-request-approval.bpmn", "utf8"))
const scenarios = JSON.parse(
  readFileSync("processes/purchase-request-approval.bpmn.tests.json", "utf8"),
) as ProcessScenario[]

for (const scenario of scenarios) {
  const engine = new Engine()
  // runScenario deploys the BPMN; deploy the decisions it calls yourself.
  engine.deploy({ decisions: Dmn.parse(readFileSync("processes/approval-matrix.dmn", "utf8")) })
  const result = await runScenario(engine, defs, scenario)
  console.log(result.passed ? "PASS" : "FAIL", scenario.name, result.failures)
}
```

What the scenarios can and cannot exercise follows from what the TypeScript engine runs (see
[Conformance](/docs/getting-started/conformance)):

- **Receive tasks** pass through in the simulator, so the scenario gives the message's
  variables as start inputs, for example `signatureStatus` in `document-signature`. On
  Camunda the receive task waits for the message with the correlation key set in the model.
- **Timer boundary events**, such as the SLA and reminder timers, are in every model. No
  scenario takes a timer path, because a scenario completes each task at once, before a
  timer can fire.
- **The AI Agent Sub-process** runs as one job in the simulator. The scenario mocks that job
  type and returns the agent's final `agent` result. The simulator does not run the tools
  inside the sub-process.
- **The inclusive split** in `employee-onboarding` ends each branch at its own end event.
  The simulator does not synchronise an inclusive join.

`casen test` runs the same scenarios on the Reebe WebAssembly engine, which has Zeebe's
semantics. Every gallery scenario passes on both engines, and the package tests check both.
Reebe runs the scenario in the same way as the simulator:

- A native user task is completed with the outputs of the `userTask` mock.
- A receive task gets its message at once, with the correlation key from the model and no
  variables. The scenario gives the message's variables as start inputs.
- An AI Agent Sub-process runs as one job. Completing the job completes the sub-process.
  The tools inside it are not run.
- An error end event throws its error code. The error boundary on the enclosing
  sub-process catches it, or an incident is raised.

## AI templates: model and secrets

Every AI step sends its API key as `{{secrets.ANTHROPIC_API_KEY}}`. Add that connector secret
to your cluster before you deploy. The model is set in one place in the package
(`TEMPLATE_MODEL`). In a template you copied, change the `provider.anthropic.model.model`
input.

The AI Agent Sub-process templates also set an `errorExpression` header. It turns a connector
failure, such as reaching the model-call limit, into the BPMN error `AGENT_FAILED`. An error
boundary on the sub-process catches it, so a failure goes to a fallback path and does not
become an incident.

## From code

```typescript
import {
  ALL_TEMPLATES,
  TEMPLATE_CATEGORIES,
  getTemplate,
  listJobTypes,
  templateFiles,
} from "@bpmnkit/patterns/templates"

const template = getTemplate("ai-evaluator-optimizer")
const defs = template?.build()                  // BpmnDefinitions, laid out
const files = template ? templateFiles(template) : [] // [{ path, content }] — what casen writes
const workers = defs ? listJobTypes(defs) : []  // job types your workers must serve
```

`build()` returns a new model on each call, so you can change it with `Bpmn.continueProcess` or
the builder before you export it.

## Add a template

Templates are TypeScript files in `packages/patterns/src/templates/`, one file per category.
Add a `ProcessTemplate` object to the file, then add it to `ALL_TEMPLATES` in `index.ts`. The
gallery test checks it with no other change: it must build, lint with no errors, round-trip,
and pass every scenario. The gallery page, the `casen template` commands and `llms.txt` all
read the same list.

---

### Simulation

Run BPMN processes locally with @bpmnkit/engine — no Camunda cluster required.

Source: https://bpmnkit.com/docs/guides/simulation

The `@bpmnkit/engine` package is a zero-dependency BPMN simulation engine that runs in
browsers and Node.js. It's useful for:

- **Testing** process logic before deploying
- **Prototyping** without a Camunda cluster
- **CI pipelines** — unit-test your process definitions
- **Demos** — run live in a browser

## Basic Usage

```typescript
import { Engine } from "@bpmnkit/engine";
import { Bpmn } from "@bpmnkit/core";

// Build a process
const xml = Bpmn.export(
  Bpmn.createProcess("order")
    .startEvent("start")
    .serviceTask("charge", { taskType: "payment" })
    .serviceTask("ship", { taskType: "shipping" })
    .endEvent("end")
    .build()
);

// Create engine and deploy
const engine = new Engine();
await engine.deploy({ bpmn: xml });

// Register workers
engine.registerJobWorker("payment", async (job) => {
  console.log("Charging card...", job.variables);
  await job.complete({ transactionId: "txn-123" });
});

engine.registerJobWorker("shipping", async (job) => {
  console.log("Shipping order...", job.variables);
  await job.complete({ trackingNumber: "1Z999AA1" });
});

// Start an instance
const instance = engine.start("order", {
  orderId: "ord-456",
  amount: 99.99,
});
```

## Instance State

The `ProcessInstance` object tracks the running state:

```typescript
const instance = engine.start("order");

console.log(instance.state);          // "running" | "completed" | "cancelled"
console.log(instance.activeElements); // Set<string> — currently active element IDs

// Subscribe to state changes
instance.onChange((newState) => {
  console.log("State changed to:", newState);
});
```

## Variables

Variables flow through the process via IO mappings. You can read the current snapshot:

```typescript
const vars = instance.variables_snapshot;
console.log(vars.orderId);       // input variable
console.log(vars.transactionId); // output from a task
```

## Message Correlation

Deliver a message to a waiting `intermediateCatchEvent`:

```typescript
// Process has a catch event waiting for "payment-confirmed"
await instance.deliverMessage("payment-confirmed", {
  paymentMethod: "card",
  confirmedAt: new Date().toISOString(),
});
```

## Step-by-Step Execution

Use the `beforeComplete` hook to pause execution between elements — useful for debugging
and building animated process runners:

```typescript
const instance = engine.start("order", {}, {
  beforeComplete: async (elementId) => {
    console.log("About to complete:", elementId);
    // Inspect state, update UI, etc.
    // Resume by returning from this function
  },
});
```

## Time Travel in the Editor

The editor's play mode (the process-runner plugin) records every engine event of a run, and a
timeline scrubber above its tabs lets you move back through them:

- **Drag the scrubber** to any event. The Variables, FEEL and Errors tabs show the state as it
  was at that event, and the canvas redraws the tokens: elements holding a token then are
  marked active, elements already passed through are marked visited.
- **Live** returns to the latest event, with the tokens as it left them.
- **Re-run with these variables** starts a new run from the start event, with the variables as
  they were at the scrubbed event, which is the quickest way to try a different branch with
  the data a real run produced.

The state is projected from the recorded log, not by re-executing the process, so scrubbing is
instant and never calls a worker twice. A run keeps up to 10,000 events.

## DMN Decision Evaluation

Deploy decision tables alongside the process:

```typescript
await engine.deploy({
  bpmn: xml,
  decisions: [dmnXml],   // DMN 1.3 XML strings
});
```

## Testing with Vitest

Write deterministic unit tests for your process logic:

```typescript
import { describe, it, expect } from "vitest";
import { Engine } from "@bpmnkit/engine";
import { buildOrderProcess } from "./processes.js";

describe("order process", () => {
  it("completes when payment succeeds", async () => {
    const engine = new Engine();
    await engine.deploy({ bpmn: buildOrderProcess() });

    let completed = false;

    engine.registerJobWorker("payment", async (job) => {
      await job.complete({ success: true });
    });

    engine.registerJobWorker("shipping", async (job) => {
      await job.complete({ trackingNumber: "TRK-001" });
    });

    const instance = engine.start("order", { amount: 50 });
    await new Promise<void>((resolve) => {
      instance.onChange((state) => {
        if (state === "completed") { completed = true; resolve(); }
      });
    });

    expect(completed).toBe(true);
    expect(instance.variables_snapshot.trackingNumber).toBe("TRK-001");
  });
});
```

## Multiple Deployments

The engine supports multiple deployed processes. Use `engine.getDeployedProcesses()` to list them:

```typescript
await engine.deploy({ bpmn: processAXml });
await engine.deploy({ bpmn: processBXml });

const processes = engine.getDeployedProcesses();
// [{ id: "process-a", name: "..." }, { id: "process-b", name: "..." }]
```

---

### Camunda 8 Deployment

Deploy and manage BPMN processes on a live Camunda 8 cluster using @bpmnkit/api.

Source: https://bpmnkit.com/docs/guides/deployment

The `@bpmnkit/api` package is a fully-typed Camunda 8 REST API client. Use it to deploy
processes, start instances, and manage your cluster from Node.js scripts, backend services,
or CI/CD pipelines.

## Setup

### SaaS (Camunda 8 Cloud)

```typescript
import { CamundaClient } from "@bpmnkit/api";

const client = new CamundaClient({
  baseUrl: "https://api.cloud.camunda.io",
  auth: {
    type: "oauth2",
    clientId: process.env.CAMUNDA_CLIENT_ID,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
    audience: process.env.CAMUNDA_AUDIENCE,
    tokenUrl: process.env.CAMUNDA_TOKEN_URL,
  },
});
```

### Self-Managed

```typescript
const client = new CamundaClient({
  baseUrl: "http://localhost:8080",
  auth: {
    type: "bearer",
    token: process.env.ZEEBE_TOKEN,
  },
});
```

### No Auth (local dev)

```typescript
const client = new CamundaClient({
  baseUrl: "http://localhost:8080",
  auth: { type: "none" },
});
```

## Deploying a Process

```typescript
import { Bpmn } from "@bpmnkit/core";
import { CamundaClient } from "@bpmnkit/api";

const xml = Bpmn.export(
  Bpmn.createProcess("invoice-approval")
    .startEvent("start")
    .userTask("review", { name: "Review Invoice" })
    .endEvent("end")
    .withAutoLayout()
    .build()
);

const result = await client.process.deploy({
  resources: [
    { content: xml, name: "invoice-approval.bpmn" },
  ],
});

console.log("Deployed version:", result.deployments[0]?.processDefinition?.version);
```

## Starting Process Instances

```typescript
const instance = await client.process.startInstance({
  bpmnProcessId: "invoice-approval",
  variables: {
    invoiceId: "inv-1234",
    amount: 2500,
    submittedBy: "alice@example.com",
  },
});

console.log("Instance key:", instance.processInstanceKey);
```

### With a Specific Version

```typescript
const instance = await client.process.startInstance({
  bpmnProcessId: "invoice-approval",
  version: 2,
  variables: { invoiceId: "inv-5678" },
});
```

## Handling Jobs

Register a long-poll job worker to process service tasks:

```typescript
const subscription = await client.jobs.activateAndProcess({
  type: "send-email",
  maxJobsToActivate: 5,
  timeout: 30_000,
  worker: "email-service",

  handler: async (job) => {
    const { to, subject, body } = job.variables;

    await sendEmail({ to, subject, body });

    await client.jobs.complete({
      jobKey: job.key,
      variables: { sent: true, sentAt: new Date().toISOString() },
    });
  },
});

// Stop the worker
subscription.close();
```

## Querying Instances

```typescript
// List running instances
const instances = await client.process.listInstances({
  bpmnProcessId: "invoice-approval",
  state: "ACTIVE",
});

// Get a specific instance
const instance = await client.process.getInstance({
  processInstanceKey: "2251799813685249",
});

// Get variables
const variables = await client.variables.list({
  processInstanceKey: instance.key,
});
```

## Managing Incidents

```typescript
// List open incidents
const incidents = await client.incidents.list({
  state: "ACTIVE",
});

// Resolve an incident (after fixing the underlying issue)
await client.incidents.resolve({ incidentKey: incident.key });
```

## Lifecycle Events

Use the TypedEventEmitter to react to API events:

```typescript
client.on("request", (e) => {
  console.log(`→ ${e.method} ${e.url}`);
});

client.on("response", (e) => {
  console.log(`← ${e.status} in ${e.durationMs}ms`);
});

client.on("error", (e) => {
  metrics.increment("camunda.api.error", { url: e.url });
});
```

## CI/CD: Deploy on Push

A typical GitHub Actions step:

```yaml
- name: Deploy BPMN processes
  run: node scripts/deploy.mjs
  env:
    CAMUNDA_CLIENT_ID: ${{ secrets.CAMUNDA_CLIENT_ID }}
    CAMUNDA_CLIENT_SECRET: ${{ secrets.CAMUNDA_CLIENT_SECRET }}
    CAMUNDA_AUDIENCE: ${{ secrets.CAMUNDA_AUDIENCE }}
    CAMUNDA_TOKEN_URL: ${{ secrets.CAMUNDA_TOKEN_URL }}
```

```typescript
// scripts/deploy.mjs
import { Bpmn } from "@bpmnkit/core";
import { CamundaClient } from "@bpmnkit/api";
import { readdir, readFile } from "node:fs/promises";

const client = new CamundaClient({
  baseUrl: "https://api.cloud.camunda.io",
  auth: {
    type: "oauth2",
    clientId: process.env.CAMUNDA_CLIENT_ID,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
    audience: process.env.CAMUNDA_AUDIENCE,
    tokenUrl: process.env.CAMUNDA_TOKEN_URL,
  },
});

const files = await readdir("./processes");
const resources = await Promise.all(
  files
    .filter((f) => f.endsWith(".bpmn"))
    .map(async (f) => ({
      name: f,
      content: await readFile(`./processes/${f}`, "utf8"),
    }))
);

const result = await client.process.deploy({ resources });
console.log(`Deployed ${result.deployments.length} processes`);
```

---

### Standalone Workers

Build, run, and deploy TypeScript workers that connect to Zeebe without any BPMNKit dependency.

Source: https://bpmnkit.com/docs/guides/workers-standalone

Workers are TypeScript programs that poll Zeebe for jobs and execute business logic.
They depend only on `@bpmnkit/worker-client` — no BPMNKit SDK required at runtime.
Run them anywhere: terminal, Docker, serverless, or via `casen worker start`.

## Scaffold a worker

The fastest way to get a worker is via the `/implement` skill, which scaffolds workers for
every service task in a generated process. You can also scaffold manually using the MCP tool:

```
Call worker_scaffold with jobType: "com.example:send-invoice:1"
```

Or generate one directly from Claude Code:

```
/implement a worker that sends invoices via SendGrid
```

Either way, the result is a directory in `./workers/`:

```
workers/
  send-invoice/
    index.ts          ← implement handle() here
    package.json
    tsconfig.json
    README.md
```

## Anatomy of a worker

```typescript
// workers/send-invoice/index.ts
import { createWorkerClient } from "@bpmnkit/worker-client"

const JOB_TYPE = "com.example:send-invoice:1"
const WORKER_NAME = "send-invoice"

const client = createWorkerClient({ workerName: WORKER_NAME })

interface Inputs {
  invoiceId: unknown // Invoice ID to send
  recipientEmail: unknown // Recipient email address
}

interface Outputs {
  // (no outputs defined)
}

async function handle(variables: Inputs): Promise<Outputs> {
  // TODO: implement send invoice logic
  throw new Error("Not implemented")
}

console.log(`[${WORKER_NAME}] polling ${JOB_TYPE}`)

for await (const job of client.poll(JOB_TYPE)) {
  try {
    const outputs = await handle(job.variables as Inputs)
    await job.complete(outputs)
    console.log(`[${WORKER_NAME}] completed ${job.key}`)
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err)
    await job.fail(msg, job.retries - 1)
    console.error(`[${WORKER_NAME}] failed ${job.key}: ${msg}`)
  }
}
```

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `ZEEBE_ADDRESS` | no | Zeebe REST base URL (default: `http://localhost:26500`) |
| `ZEEBE_CLIENT_ID` | Camunda SaaS only | OAuth2 client ID |
| `ZEEBE_CLIENT_SECRET` | Camunda SaaS only | OAuth2 client secret |
| `ZEEBE_TOKEN_URL` | no | OAuth2 token URL (default: Camunda SaaS endpoint) |
| `ZEEBE_TOKEN_AUDIENCE` | no | OAuth2 audience (default: `zeebe.camunda.io`) |

For local development with reebe, only `ZEEBE_ADDRESS` matters (or leave it at the default).

## Running workers

### Development (tsx, no build step)

```sh
cd workers/send-invoice
npm install
npm start          # runs: tsx index.ts
```

### Production (compiled JS)

```sh
cd workers/send-invoice
npm install
npm run build      # runs: tsc
npm run start:prod # runs: node dist/index.js
```

### All workers at once

```sh
casen worker start
```

To start a specific worker:

```sh
casen worker start send-invoice
```

## Docker

Each scaffolded worker includes a multi-stage `Dockerfile` recipe in its README:

```dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY index.ts tsconfig.json ./
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/index.js"]
```

Build and run:

```sh
docker build -t my-org/send-invoice .
docker run -e ZEEBE_ADDRESS=http://reebe:26500 my-org/send-invoice
```

## Camunda SaaS

For Camunda 8 cloud, pass OAuth2 credentials as environment variables:

```sh
ZEEBE_ADDRESS=https://your-cluster.bru-2.zeebe.camunda.io:443 \
ZEEBE_CLIENT_ID=... \
ZEEBE_CLIENT_SECRET=... \
npm run start:prod
```

`@bpmnkit/worker-client` handles OAuth2 token fetching and caching automatically.

## Listing available workers

```sh
casen worker start --help
```

Or from Claude Code, call `worker_list` to see all built-in and scaffolded workers:

```
worker_list()
```

Built-in workers (provided by the proxy):

| Job type | Description |
|---|---|
| `bpmnkit:llm:1` | Call an LLM and return the response text |
| `bpmnkit:cli:1` | Run a shell command |
| `bpmnkit:http:scrape:1` | Fetch and extract text from a URL |
| `bpmnkit:fs:read:1` | Read a file from the local filesystem |
| `bpmnkit:fs:write:1` | Write content to a file |
| `bpmnkit:fs:append:1` | Append content to a file |
| `bpmnkit:fs:list:1` | List files in a directory |
| `bpmnkit:js:1` | Evaluate a JavaScript expression |
| `bpmnkit:email:fetch:1` | Fetch email from an IMAP mailbox |
| `bpmnkit:email:send:1` | Send email via SMTP |

## See also

- [`@bpmnkit/worker-client`](/docs/packages/worker-client) — full API reference
- [AI-Driven Implementation](/docs/guides/ai-implement) — scaffold workers as part of `/implement`

---

### Using BPMN Kit with AI

Give an AI agent the three things it needs to build a process — BPMN Kit's own docs, Camunda's docs, and your team's prose — all indexed offline, then generate the BPMN.

Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

An agent asked to turn a folder of specs into a deployable process needs three
different kinds of knowledge, and only one of them is in its weights:

| It needs to know | Where that lives | How it asks |
| --- | --- | --- |
| How to drive this library | `@bpmnkit/docspack` | `bpmnkit-docs ask "…"` |
| How the engine behaves | `@bpmnkit/camunda-docspack` | `bpmnkit-docs ask "…" --pack @bpmnkit/camunda-docspack` |
| What the process actually does | your own Markdown | index it yourself, below |

All three are offline retrieval. Nothing here calls a model, starts a server or
touches the network, so a question costs milliseconds and no tokens. The model
is only spent on the last step — turning what it found into a diagram.

## The two packs BPMN Kit ships

```sh
npm i -D @bpmnkit/docspack @bpmnkit/camunda-docspack
```

**[`@bpmnkit/docspack`](/docs/packages/docspack)** carries the documentation you
are reading — the builder API, the CLI, the guides — pinned to the version this
project installed.

**[`@bpmnkit/camunda-docspack`](/docs/packages/camunda-docspack)** carries the
Camunda 8 documentation: BPMN and FEEL references, engine concepts, the
best-practice pages with their diagrams rendered as text, and one digest per
Orchestration Cluster API operation. It is Camunda's work, redistributed under
CC BY-SA 3.0, not documentation BPMN Kit wrote.

One `bpmnkit-docs` command reads both.

## Telling an agent they exist

An agent that does not know a pack is installed will answer from memory instead,
and its memory describes an older release. One paragraph in `AGENTS.md`,
`CLAUDE.md` or `.cursor/rules` is the whole setup — **name both packs**, because
an agent told only about the first will never think to ask the second:

```md
Documentation is installed locally. Ask it before answering from memory.

- BPMN Kit's own APIs, CLI and guides:
  `npx bpmnkit-docs ask "<question>"`
- Camunda 8 — BPMN semantics, FEEL, engine behaviour, the REST API:
  `npx bpmnkit-docs ask "<question>" --pack @bpmnkit/camunda-docspack`

A returned chunk beats recalled knowledge: it describes the version this project
installed. If the two disagree, the chunk is right — do not blend them.
Answers cap at 3 chunks / 3,000 tokens, so ask several narrow questions rather
than one broad one.
```

## Asking

```sh
npx bpmnkit-docs ask "what does compactify drop from a diagram"
```

```
## @bpmnkit/docspack@0.0.5/packages.core.installation-compactify-definitions

Projects a `BpmnDefinitions` object onto a `CompactDiagram` — a small JSON
object suitable for LLM prompts. **Lossy:** it keeps topology, names …

---
cost: 204 tokens, capped at 3,000
```

Every answer names the pack, the version and the chunk, and closes with what it
cost — so an agent can quote the chunk id back when a passage turns out to be
wrong.

Ask the engine's documentation with `--pack`:

```sh
npx bpmnkit-docs ask "what happens when no exclusive gateway condition is true" \
  --pack @bpmnkit/camunda-docspack
```

`--pack` is worth using even when you are not disambiguating. Building the index
reads every chunk off disk, so narrowing to one pack is the difference between
roughly 150ms and 650ms per question. A name that is not installed is an error
listing what is, never an empty answer — an empty answer would read as "the
documentation does not cover this", which is a different claim.

`search` ranks without printing the content, and `list` shows what was found:

```sh
npx bpmnkit-docs search "exclusive gateway condition"
npx bpmnkit-docs list
```

```
@bpmnkit/camunda-docspack@0.1.1  1054 chunks
@bpmnkit/docspack@0.0.5  206 chunks
```

## From the library instead of the CLI

A long-lived agent, an editor extension or an MCP server should index once and
ask many times, rather than paying for the index on every question:

```typescript
import { answer, discoverPacks, indexPacks } from "@bpmnkit/docspack";

const index = indexPacks(discoverPacks());

const { hits, tokens } = answer(index, "verify a worker's job type", {
  packs: ["@bpmnkit/docspack"],
  limit: 3,
  maxTokens: 3000,
});

for (const hit of hits) console.log(hit.chunkId, hit.content);
console.log(`${tokens} tokens`);
```

## Indexing your own corpus

The packs above answer for BPMN Kit and for Camunda. Nothing answers for *your*
process — the five Markdown files somebody wrote describing how orders are
fulfilled. Handed the folder, an agent reads the wrong file or spends its whole
context on all of them; a corpus larger than the context window cannot be read
into it at all.

Index it, and it becomes something the agent asks questions of. The same builder
behind `bpmnkit-docs build` takes any folder of Markdown:

```sh
mkdir -p flow-corpus
cat > flow-corpus/package.json <<'JSON'
{
  "name": "order-fulfilment-corpus",
  "version": "1.0.0",
  "private": true,
  "docspack": { "source": "../flow-docs", "minTokens": 60, "maxTokens": 800 }
}
JSON

npx bpmnkit-docs build --cwd flow-corpus
npx bpmnkit-docs ask "when does an order need manager approval" --cwd flow-corpus
```

```
Built 5 chunks from 5 documents (421 tokens).

## order-fulfilment-corpus@1.0.0/02-approval.when-approval-is-needed

# Approval — When approval is needed

An order over 10000 EUR needs a regional manager to approve it before anything
is picked. At or under that figure the order goes straight to fulfilment.
```

Indexing runs no model, so building the corpus costs no tokens — five documents
take about 9ms.

A few things decide whether the result is any good:

- **Split at headings that answer something.** A chunk is a `##` section.
  `minTokens` merges a section too short to answer anything into the one before
  it, so a two-line heading does not become a chunk of its own.
- **`--cwd` points at the pack, not at the sources.** A directory holding a
  `package.json` and a `.llms/` payload *is* a pack, so `bpmnkit-docs` reads it
  without it ever being published.
- **Your corpus and the installed packs are searched together.** Discovery walks
  `node_modules` up from `--cwd`, so a corpus inside your project sees
  `@bpmnkit/docspack` too, and `--pack` narrows to whichever you want.
- **Keep it out of git, and re-index after editing.** The chunks are a copy of
  your files. Edit a source and the index is stale until you build again —
  `bpmnkit-docs build` is cheap enough to run on every change.
- **Tags weigh 3× prose.** Front matter, the slug and the heading's own words
  become tags automatically; steer them from the document itself when the words
  a reader would search for are not the words on the page:

  ```md
  ## Escalation

  <!-- docspack: tags=carrier,refused,dispatcher -->
  ```

### The other route: `docspack index`

Upstream [docspack](https://docspack.dev) 1.1.0 added
[a second way to do this](https://docspack.dev/docs/your-own-corpus/). Rather than
building a pack, it keeps an SQLite index of loose sources, and answers from it
with `recall` instead of `ask`:

```sh
npm i -D docspack

npx docspack index --from ./flow-docs
npx docspack recall "when does an order need manager approval"
```

```
indexing @local/flow-docs
+ @local/flow-docs  10 chunks  ~527 tokens
```

Pick it over `bpmnkit-docs build` when the corpus is not a folder of Markdown.
Anything that emits JSON can be indexed without a database driver:

```sh
sqlite3 -json shop.db 'select id, title, body as text from orders'   | npx docspack index --from-json -
```

It also tracks each source's size, mtime and hash, so a re-run does nothing when
nothing changed, and `recall` leads with a warning rather than quoting a passage
that has since been edited:

```
NOTE: the corpus is out of date. 1 indexed source has changed since it was
built: flow-docs/04-shipping.md. The passages below may be superseded — run
`docspack index` again before relying on them.
```

`recall` is deliberately not `ask`: your notes are never an installed version, so
a corpus cannot reach an answer about a dependency and a dependency cannot reach
an answer about your notes. The index lands in `.docspack/local.db` as plaintext
and the tool writes a `.gitignore` beside it.

The two routes do not merge. `bpmnkit-docs` searches your corpus and the
installed packs together because a pack directory is just a directory; upstream
keeps them in separate query paths on purpose. Build a pack when you want one
answer drawn from both; use `docspack index` when the corpus is a database, or
when you want the staleness check.

> **Use `docspack@1.2.0` or newer for the Camunda pack.** Earlier versions named
> one pack per npm scope, so `docspack sync` read `@bpmnkit/camunda-docspack` as
> an ordinary dependency and indexed its type declarations — `0 chunks
> (declarations)` — leaving a Camunda question to be answered out of the wrong
> pack. 1.2.0 discovers `@<vendor>/<name>-docspack` and indexes all 1,054 chunks.
> `bpmnkit-docs` has read the suffix from the start and needs no version floor.

## The whole loop: five Markdown files to a BPMN diagram

Put the three together and the agent's job is narrow enough to be reliable:

1. **Index the team's prose** and ask it what the flow actually does — where the
   thresholds are, what runs in parallel, what happens on the unhappy path.
2. **Ask `@bpmnkit/docspack`** how to express that with this library.
3. **Ask `@bpmnkit/camunda-docspack`** whatever the engine, not the library,
   decides — gateway semantics, FEEL syntax, job types.
4. **Return a `CompactDiagram`**, not XML. About 40 lines of JSON for a diagram
   that is 200 lines of BPMN, and a model that has never written valid BPMN XML
   can still produce a valid diagram.
5. **`expand` it**, which is deterministic — layout included.

```typescript
import { Bpmn, expand } from "@bpmnkit/core";
import type { CompactDiagram } from "@bpmnkit/core";
import { answer, buildPack, indexPacks, loadPack } from "@bpmnkit/docspack";

// 1. The team's own files, indexed.
buildPack({
  source: "flow-docs",
  packDir: "flow-corpus",
  name: "order-fulfilment-corpus",
  version: "1.0.0",
  documents: ["order-fulfilment-corpus"],
  minTokens: 60,
});
const corpus = indexPacks([loadPack("flow-corpus")]);

const facts = ["when does an order need manager approval", "what runs in parallel"]
  .flatMap((q) => answer(corpus, q, { limit: 1, maxTokens: 600 }).hits)
  .map((hit) => hit.content);

// 2–4. The model reads `facts` and returns this. Nothing here is XML.
const compact: CompactDiagram = await writeDiagram(facts);

// 5. Deterministic from here on: topology, Zeebe bindings and layout.
const definitions = expand(compact);
const xml = Bpmn.export(definitions);
```

**Mark every gateway's fallthrough branch.** An exclusive gateway whose
conditions are all false and which has no default deadlocks at runtime, so the
branch without a condition carries `isDefault` instead:

```typescript
flows: [
  { id: "f5", from: "needsApproval", to: "approveOrder", condition: "= total > 10000" },
  { id: "f6", from: "needsApproval", to: "splitWork", name: "at or under", isDefault: true },
]
```

`expand` turns it into the gateway's `bpmn:default` attribute, `compactify` reads
it back, and `reconcileCompact` sets it on a file somebody else authored. A flow
marked `isDefault` that does not leave an exclusive, inclusive or complex
gateway, or a gateway with two of them, throws rather than being dropped.

> `CompactDiagram` still does not model everything. See
> [AI Integration](/docs/guides/ai) for what it drops, and use `reconcileCompact`
> rather than `expand` when you are editing a file you need to keep.

## Runnable examples

Three scripts in [`apps/examples/src/ai`](https://github.com/bpmnkit/bpmnkit/tree/main/apps/examples/src/ai)
do exactly the above. They need no API key and no network — the whole set runs
in about three seconds:

```sh
pnpm --filter @bpmnkit/examples ai:ask     # ask both packs, from the library
pnpm --filter @bpmnkit/examples ai:index   # 5 Markdown files → an askable corpus
pnpm --filter @bpmnkit/examples ai:bpmn    # corpus → CompactDiagram → .bpmn
```

`ai:bpmn` writes `output/order-fulfilment.bpmn`: 18 elements, 20 sequence flows,
laid out, with the gateway defaults set.

## Keeping it fast

| What | Cost | Why |
| --- | --- | --- |
| `ask` scoped with `--pack @bpmnkit/docspack` | ~150ms | indexes one pack |
| `ask` across both packs | ~650ms | indexes both, 1,200+ chunks |
| `indexPacks` once, then `answer` per question | ~0ms per question | the index is the expensive part |
| Building a 5-document corpus | ~9ms | no model, no network |

Reading chunks off disk dominates, and a fresh `npx bpmnkit-docs ask` pays it on
every question. Scope with `--pack` when you know which pack answers; use the
library and hold the index when you are asking more than a handful of questions.

## Where to go next

- [AI Integration](/docs/guides/ai) — the compact format, prompting, the Claude
  and OpenAI calls, and the MCP server
- [Building Processes with AI](/docs/guides/ai-implement) — the `ProcessPlan`
  pipeline, which compiles rather than generating XML
- [AI Agents](/docs/guides/ai-agents) — putting an LLM *inside* a process as a
  Camunda AI Agent Sub-process
- [Claude Code Plugin](/docs/guides/claude-code-plugin) — the slash commands that
  drive all of it

---

### AI Integration

Use BPMN Kit with LLMs to generate and modify process diagrams from natural language.

Source: https://bpmnkit.com/docs/guides/ai

BPMN Kit is designed from the ground up to work with AI agents. The compact intermediate
format lets a complete process diagram fit in a single LLM prompt, and the builder API
produces valid BPMN without requiring the AI to write raw XML.

## The Compact Format

Raw BPMN XML is far too verbose for LLMs — a simple three-node process generates ~60 lines.
The compact format carries the topology and the common Zeebe bindings as a small JSON object:

```typescript
import { Bpmn, compactify, expand } from "@bpmnkit/core";

// Parse some BPMN XML
const definitions = Bpmn.parse(existingXml);

// Convert to compact format
const compact = compactify(definitions);
// compact is ~500 tokens for a typical approval workflow

// Send to your LLM, get back a modified compact object
const modified = await llm.modify(compact, "Add a parallel notification step after approval");

// Convert back to full BPMN
const updatedDefinitions = expand(modified);
const updatedXml = Bpmn.export(updatedDefinitions);
```

> **`expand()` does not restore what `compactify()` left behind.** `CompactElement` models
> about fifteen properties; collaborations, participants, message flows, lanes, data stores,
> artifacts, root-level messages and errors, multi-instance loop characteristics, full
> `zeebe:ioMapping` entries and most diagram interchange are not among them.
>
> The loop above is safe for a model **you generated** from a compact definition. Running it
> over a file authored elsewhere — a Camunda blueprint, anything touched in Web Modeler —
> will silently strip those parts.
>
> **Use `reconcileCompact` instead when editing an existing file.** It applies the same compact
> input as changes rather than expanding it over the model, so what the compact form cannot
> describe survives:
>
> ```typescript
> import { reconcileCompact } from "@bpmnkit/core";
>
> const { definitions } = reconcileCompact(Bpmn.parse(existingXml), modified);
> const updatedXml = Bpmn.export(definitions);
> ```
>
> If the model returns edit operations rather than a whole diagram, `applyBpmnOperations` takes
> them directly against the full model.

## Minimal Empty Diagram

When an AI agent needs to start fresh, use `Bpmn.makeEmpty()` to get a valid starting point
with a single start event:

```typescript
import { Bpmn } from "@bpmnkit/core";

// Returns a valid BPMN XML string — one start event, ready for an agent to extend
const xml = Bpmn.makeEmpty("my-process", "My Process");
```

## Prompting Strategy

For best results, give the LLM the compact diagram and a clear instruction. A good system
prompt excerpt:

```
You are a BPMN process designer. The user will describe a business process and you will
return a CompactDiagram JSON object.

Rules:
- Use camelCase IDs
- Every service task needs a jobType string (the Zeebe worker subscription)
- Use FEEL expressions for gateway conditions (start with "= ")
- Every exclusive gateway needs one branch with no condition and `isDefault: true`
- Always include a start event and at least one end event
- Do not add fields that are not part of the CompactDiagram schema
```

## Claude API Example

Using the Anthropic SDK to generate a process from a description:

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { Bpmn, expand } from "@bpmnkit/core";
import type { CompactDiagram } from "@bpmnkit/core";

const anthropic = new Anthropic();

async function generateProcess(description: string): Promise<string> {
  const response = await anthropic.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 2048,
    system: `You are a BPMN process designer. Return only valid JSON matching the
CompactDiagram schema. No explanation, no markdown — raw JSON only.`,
    messages: [
      {
        role: "user",
        content: `Create a BPMN process for: ${description}`,
      },
    ],
  });

  const json = response.content[0];
  if (json?.type !== "text") throw new Error("Unexpected response type");

  const compact = JSON.parse(json.text) as CompactDiagram;
  const definitions = expand(compact);

  return Bpmn.export(definitions);
}

const xml = await generateProcess(
  "An invoice approval process where invoices over $10,000 need manager approval"
);
```

## OpenAI Function Calling

Use function/tool calling for reliable structured output:

```typescript
import OpenAI from "openai";
import { expand, Bpmn } from "@bpmnkit/core";

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: "Create a customer onboarding process with email verification and KYC check",
    },
  ],
  tools: [
    {
      type: "function",
      function: {
        name: "create_bpmn_process",
        description: "Create a BPMN process diagram",
        parameters: compactDiagramJsonSchema, // export from @bpmnkit/core
      },
    },
  ],
  tool_choice: { type: "function", function: { name: "create_bpmn_process" } },
});

const toolCall = response.choices[0]?.message.tool_calls?.[0];
if (!toolCall) throw new Error("No tool call");

const compact = JSON.parse(toolCall.function.arguments);
const xml = Bpmn.export(expand(compact));
```

## Previewing While the Model Writes

A diagram is visual, and a model takes seconds to write one. Waiting for the last token to
show anything means the user watches prose scroll past while the only interesting part of the
answer is already most of the way written.

Nothing downstream can use a half-written document, though — `JSON.parse` wants the closing
brace, and the outermost one is the very last character a tool call sends.
`createCompactStream` sidesteps that by not parsing the document at all. It takes complete
`{…}` literals as they close and keeps the ones shaped like an element or a flow, which are
the innermost objects and so the first to finish:

```typescript
import { createCompactStream } from "@bpmnkit/core";

const stream = createCompactStream({ base: currentDiagram });

for await (const chunk of tokens) {
  const frame = stream.push(chunk); // null until the frame changes
  if (frame) canvas.loadDefinitions(frame, { keepViewport: true });
}
```

Pass `base` when the model is editing something. It streams only what it is adding, so without
the diagram it started from a frame is a disconnected fragment rather than the process with the
fragment in it.

`keepViewport` matters as much as the frames do: without it the canvas re-frames the diagram on
every update and pulls the view out from under whoever is watching. With it, the process grows
in place — the layout is stable enough for that, because appending to a diagram does not move
what is already placed.

### Frames are advisory

Every frame is a guess at an unfinished document. `push` never throws, drops what it cannot
place, and strips a flow's `isDefault` rather than failing when the gateway it claims has not
arrived. That is the whole bargain: a frame that guesses wrong costs one render, so the
authoritative result is whatever the model finishes with, and that is what you save or deploy.

### Where the frames come from

The local proxy (`bpmn-ai-server`) sends them on `/chat` as `preview` events, from two places:

- **The tool call being written** — argument fragments as they stream, which is the only thing
  that covers a process the model composes in a single call.
- **The MCP server's own state** — one frame per mutating tool call, once anything has been
  written. These take over as soon as they exist; they are the model's own state rather than a
  guess at an unfinished document.

A client renders `preview` as it likes and treats the `xml` event at the end of the stream as
the result. The editor's AI panel does this, and additionally outlines the elements the diagram
being edited does not have — so an edit reads as an edit rather than a rewrite. It marks
nothing when the diagram has no sequence flows yet: a process built from scratch is new all the
way through, and marking everything says no more than marking none of it.

### What the model can do

The proxy runs your installed `claude`, `copilot` or `gemini` CLI for the AI panel, but not as
a coding agent. The model gets no shell, no file access and no web access, and none of your
own MCP servers, settings or plugins. What it can do depends on the request:

| Request | The model gets |
|---|---|
| AI panel chat, improve, explain (`/chat`) | The diagram tools of the proxy's MCP server, which change only the diagram held in that server's memory. The result comes back as the `xml` event; nothing is written to your project. |
| Create form or decision (`/chat`), improve with operations (`/improve`, `casen lint --ai`), Operate chat, incident assist, AI search, `casen ask` | No tools. The model answers with text or JSON, and the proxy does the rest. |

Everything that comes from the request — your chat text, the diagram, an incident's variables —
reaches the model inside `<untrusted-input>` tags, and the system prompt tells it to treat that
as data. A diagram that says "ignore your instructions" is still just a diagram.

## MCP Server

BPMN Kit ships a Model Context Protocol (MCP) server that lets any MCP client — Claude Code,
Claude Desktop, Cursor, VS Code — create, validate, simulate and deploy processes. It speaks
stdio and is started by the CLI:

```sh
casen proxy mcp
```

or, without installing the CLI first, in an MCP client's configuration:

```json
{
  "mcpServers": {
    "bpmnkit": { "command": "npx", "args": ["-y", "@bpmnkit/cli", "proxy", "mcp"] }
  }
}
```

Each CLI release submits it to the [MCP Registry](https://registry.modelcontextprotocol.io)
as `io.github.bpmnkit/bpmnkit`.

Tools:

- `bpmn_create`, `bpmn_read`, `bpmn_update` — write and read `.bpmn` files through the compact
  format, with auto-layout applied on write
- `bpmn_validate` — run the optimizer's findings over a file
- `bpmn_simulate`, `bpmn_run_history` — run a process on the local engine and read past runs
  (needs the proxy running: `casen proxy start`)
- `bpmn_deploy` — deploy to the active `casen` profile (Camunda 8 or a local Reebe)
- `form_create`, `dmn_create` — Camunda Forms and DMN decision tables
- `worker_list`, `worker_scaffold` — list and generate job workers
- `pattern_list`, `pattern_get` — the domain patterns in `@bpmnkit/patterns`
- `camunda_search`, `camunda_execute` — discover and call any Camunda 8 REST operation

The [Claude Code plugin](/docs/guides/claude-code-plugin) configures this server for you.

---

### Building Processes with AI

Go from a natural language description to a deployed, tested BPMN process — via a deterministic ProcessPlan pipeline, never hand-written XML.

Source: https://bpmnkit.com/docs/guides/ai-implement

BPMNKit's AI pipeline never asks an LLM to write BPMN XML. Every process is authored as a
`ProcessPlan` JSON file and compiled deterministically by `casen synth` — this is what makes
generated processes reliably valid, deployable, and easy to diff. The LLM's job is narrower and
more reliable: write the plan, resolve connectors, and fix reported problems.

## The pipeline

```
"implement X" (natural language)
        │
        ▼
  ProcessPlan JSON  ──casen synth──▶  laid-out, deployable .bpmn
        │                                    │
        │                            casen lint --profile deploy
        │                                    │
        └──casen plan extract◀────────  casen test
                (for later edits)
```

1. **Check for a reusable domain pattern** — `casen pattern list`/`get` (see [Pattern Library](/docs/guides/patterns)) surfaces domain context (regulations, conventions) and realistic worker specs, used as reference while writing the plan below — not pasted in as a `ProcessPlan` directly.
2. **Resolve external interactions** — `casen connector search "<system>"` / `casen connector show <template-id>` find the right Camunda connector template and its required inputs, instead of guessing property keys.
3. **Write the plan** — a `ProcessPlan` JSON file (`casen plan schema` prints the full format reference).
4. **Compile** — `casen synth <plan>.json --output <file>.bpmn`. Problems are reported keyed by JSON path (e.g. `steps[2].connector.values.token`) — fix the plan, never the XML, and re-run.
5. **Test** — a `tests` array in the plan compiles to a `<file>.bpmn.tests.json` sidecar automatically; run it with `casen test <file>.bpmn`.
6. **Deploy-readiness gate** — `casen lint <file>.bpmn --profile deploy` must report zero errors before deploying.
7. **Deploy** — `casen deploy deploy <file>.bpmn` (local Reebe) or `--target camunda8`.

## The Claude Code plugin

The richest way to drive this pipeline is the `bpmnkit` Claude Code plugin:

```sh
/plugin marketplace add github:bpmnkit/bpmnkit
/plugin install bpmnkit
```

It's **CLI-first**: every skill drives `casen` via Bash — no MCP server, no proxy daemon. Each skill reads the relevant generated/hand-written reference doc (plan format, connector catalog, agentic pattern, FEEL syntax, modeling conventions) before authoring a plan.

```
/bpmnkit:implement an invoice approval process for accounts payable
```

Claude works through: resolve connectors → write the plan → compile → test → scaffold missing workers → present a summary → ask where to deploy.

Related skills: `/bpmnkit:extend <file> <change>` (lift an existing process to a plan, apply a targeted delta, merge), `/bpmnkit:agent` (design an AI Agent Sub-process — see [AI Agents](/docs/guides/ai-agents)), `/bpmnkit:connect <file> <step> <service>` (wire an existing step to a connector), `/bpmnkit:review`, `/bpmnkit:test`, `/bpmnkit:deploy`.

## Lightweight alternative: `casen skills install`

If you don't want the full plugin, four minimal slash commands are available directly from the CLI — see [AIKit Skills](/docs/cli/skills):

```sh
casen skills install
```

This installs `/implement`, `/review`, `/test`, `/deploy` into `.claude/commands/`. Same underlying pipeline, less scaffolding around it (no `/extend`/`/agent`/`/connect`, no generated reference docs).

## What gets created

```
project/
  invoice-approval.plan.json         ← the source of truth — edit this, not the XML
  invoice-approval.bpmn              ← compiled by casen synth
  invoice-approval.bpmn.tests.json   ← scenarios, if the plan had a `tests` array
  workers/
    validate-invoice/
      index.ts                       ← implement the job logic here
      package.json
      tsconfig.json
      README.md
```

## Deploying

```
Deploy to local Reebe, deploy to Camunda 8, or skip?
```

- **Local Reebe** — deploys via `ZEEBE_ADDRESS` (default `http://localhost:26500`). Start Reebe first: `casen reebe start --port 26500`.
- **Camunda 8** — deploys using the active `casen` profile. Set one up with `casen profile create`.
- **Skip** — leaves the plan and BPMN file on disk for manual review and deployment.

## Implementing workers

Each scaffolded worker uses `@bpmnkit/worker-client`'s real polling API:

```typescript
// workers/validate-invoice/index.ts
import { createWorkerClient } from "@bpmnkit/worker-client"

const client = createWorkerClient({ workerName: "validate-invoice-worker" })

for await (const job of client.poll("validate-invoice:1")) {
  try {
    // TODO: implement invoice validation
    await job.complete({ /* output variables */ })
  } catch (err) {
    await job.fail(String(err))
  }
}
```

Start a worker for development:

```sh
cd workers/validate-invoice
npm install
npm start
```

Or start all workers at once:

```sh
casen worker start
```

See [Standalone Workers](/docs/guides/workers-standalone) for deployment options.

## Extending an existing process

```
/bpmnkit:extend invoice-approval.bpmn add a timeout boundary event to the approval task
```

This lifts the process back into plan form (`casen plan extract`), writes a small delta plan touching only the changed step, and merges it in (`casen synth --merge`) — the diff is reported at the element level, not as an XML diff.

---

### Connectors in AI Generation

How BPMN Kit turns "post the open GitHub issues to Slack" into an executable process — connector cards, with lines, the offline API index, and a dry run that proves it runs.

Source: https://bpmnkit.com/docs/guides/ai-connectors

A generated diagram is only useful in Camunda 8 if its calls to outside systems are
configured connectors: the right template, the inputs it needs, credentials as secrets. BPMN
Kit does this in code wherever it can and asks a model only for what code cannot know. All
the connector data ships in the packages, so nothing is fetched at run time.

## Two passes

1. **The shape.** A model writes the process in the
   [line format](/docs/packages/core#parseprocesstexttext-and-createprocesstextstream): tasks,
   gateways, events. Each call to an outside system is its own service task.
   In Drop, code then checks the draft against the request. A DMN decision, a time limit or a
   REST call the request names, with no rule task, timer or error boundary for it in the draft,
   gets one change request asking for exactly that. A complete draft skips it.
2. **The connectors.** A second, small call configures them. Code picks the connector cards
   each task could use and sends only those. The model answers with `with` lines only, and
   code applies them.

The second pass is skipped without a model call when no task matches a connector. A pure
approval flow costs nothing extra.

## Connector cards

The 133 Camunda connector templates are bundled in
[`@bpmnkit/core/connectors`](/docs/packages/connectors). A template with several operations
becomes one **card** per operation, with only the inputs that operation uses:

```
slack chat.postMessage — Slack Outbound Connector: Post message | token*(secret) data.text* data.channel* | optional: data.thread resultVariable resultExpression(=FEEL)
```

`*` marks a required input. `(secret)` takes a `{{secrets.NAME}}` placeholder.

- **Picking cards.** `selectConnectors({ text, tasks })` picks the cards for each task, in
  code. A card fits when the task's name names the system ("Post summary to **Slack**"), or
  when the request names it and no other task does.
- **Searching.** `findConnectorCards(query)` searches all cards.
- **From a terminal.** `casen connector cards "post a message to slack"` prints them.

## `with` lines

A `with` line configures one node:

```
with notify: slack chat.postMessage | token={{secrets.SLACK_TOKEN}} | data.channel=#ops | data.text== "Order " + orderId + " failed"
with fetch: http GET https://api.example.com/orders | result=order: response.body
```

`applyConnectorLines` resolves the line against the catalog and applies the template. A
plain task becomes the connector's service task. The resolver repairs what models get nearly
right:

- a misspelt alias;
- a short key (`channel` for `data.channel`);
- a credential written as a value, which becomes a secret placeholder.

A required input the line left out becomes a **question**, with a line for the reader to
finish. The [`with` lines reference](/docs/packages/connectors#with-lines) has the details.

## Any HTTP API

Most systems have no dedicated connector. The REST connector reaches them, but only with the
right base URL, path and authentication. The
[API index](/docs/packages/connector-gen#api-index) has these for about 80 APIs, built offline
from their OpenAPI specs. A task that names one of them gets an **API card** next to the REST
connector:

```
api stripe — Stripe API https://api.stripe.com auth=bearer secret=STRIPE_TOKEN
POST /v1/customers — Create a customer | form body: name email description address balance business_name
```

The model writes `api=stripe` and the path:

```
with customer: http POST /v1/customers | api=stripe | body=={email: email}
```

The line then gets:

- the base URL;
- the `{params}` of the path as FEEL, from variables of the same name;
- the authentication, with a `{{secrets.STRIPE_TOKEN}}` placeholder;
- the headers the endpoint needs, such as Stripe's form encoding or Notion's
  `Notion-Version`.

A call the index does not have is kept, as a question to check the URL. A dedicated
connector still wins when it covers the task. GitHub's connector creates issues; the index
lists workflow runs.

## Proving it runs

A diagram that parses is not yet a process that runs. Two checks follow every connected
result:

- **Dry run.** [`dryRun`](/docs/guides/testing-processes#dry-run) runs the process once from
  start to end. Every connector answers an empty HTTP 200, and every other job completes.
  Messages are delivered and timers fire. It says whether the run reached the end, or where
  it stopped and why.
- **Secrets.** `listSecrets` lists every secret the diagram reads, so you can create them in
  the cluster before deploying.

## Where you meet it

- **[Drop](/docs/guides/drop).** "Describe a process" drafts the diagram, connects it, and
  shows the secrets and the dry run. A shared diagram has **Add connectors** while editing.
- **CLI.**
  - `casen connector cards "<request>"` prints connector cards.
  - `casen connector api "<request>"` prints the endpoints of an indexed API.
  - `casen synth --check` dry-runs a compiled plan and lists its secrets.
- **The proxy's MCP server.** It is used by the AI chat and by your own agents:
  - `find_connectors { query }` returns cards and API endpoints.
  - `add_connector { processId, id, alias, operation, values }` configures a node through
    the same resolver.
- **Studio.** **Try it** runs a model on the local engine. GET requests go out for real;
  every other connector and task is simulated.

## Keeping the data current

- **Connector templates.** They come from Camunda's marketplace registry.
- **API index.** It is built from the connector-gen catalog's specs.

A weekly workflow refreshes both and opens a pull request when something changed. Specs that
state a non-commercial, copyleft or proprietary license are not indexed.

---

### AI Agents

Add a Camunda 8 AI Agent Sub-process to a BPMN process — an LLM-in-the-loop step that can call tools, generated deterministically like everything else in the pipeline.

Source: https://bpmnkit.com/docs/guides/ai-agents

Camunda 8's **AI Agent Sub-process** lets a single process step delegate to an LLM that can
call tools (other BPMN activities) in a loop until it produces a final answer. BPMNKit
generates this pattern the same way it generates everything else: deterministically, from a
`ProcessPlan` — never by hand-writing the underlying ad-hoc-sub-process XML.

## Quick start

```
/bpmnkit:agent add a support-triage agent with tools: search KB (http), escalate to human (user task), post summary to slack
```

Or, from the CLI directly: write an `aiAgent` plan step (see below), then `casen synth`.

## How it's modeled

- A `bpmn:AdHocSubProcess` carrying a `zeebe:taskDefinition` of type `io.camunda.agenticai:aiagent-job-worker:1` — the presence of `zeebe:taskDefinition` is itself what marks it as a job-worker implementation.
- Each **tool** is a root-node activity inside the sub-process (no incoming sequence flow). The tool's element id is its name as the LLM sees it; its documentation is the description the LLM reads.
- Parameters the LLM must supply are `fromAi(toolCall.<param>, "<description>", "<type>"?, <jsonSchema>?, {required: false}?)` FEEL expressions.
- Each tool's result is aggregated into an `outputCollection` (default `toolCallResults`); the agent's own final answer lands in a process variable (default `agent`).

None of this is hand-authored — it's generated by the `aiAgent` plan step.

## The `aiAgent` plan step

```json
{
  "kind": "aiAgent",
  "id": "triage_agent",
  "name": "Triage agent",
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "providerInputs": {
    "provider.anthropic.authentication.apiKey": "{{secrets.ANTHROPIC_API_KEY}}"
  },
  "systemPrompt": "You triage support tickets and post updates to Slack.",
  "userPrompt": "=ticketText",
  "tools": [
    {
      "id": "notify_slack",
      "description": "Post a status update to the #support-escalations Slack channel.",
      "connector": {
        "template": "io.camunda.connectors.Slack.v1",
        "values": {
          "method": "chat.postMessage",
          "token": "{{secrets.SLACK_OAUTH_TOKEN}}",
          "data.channel": "#support-escalations",
          "data.text": "placeholder"
        }
      },
      "params": [
        { "name": "message", "description": "The status update to post", "type": "string", "target": "data.text" }
      ]
    },
    {
      "id": "escalate",
      "description": "Escalate the ticket to a human agent.",
      "jobType": "escalate:1",
      "params": [{ "name": "reason", "description": "Why this needs a human" }]
    }
  ],
  "errorBoundary": {
    "errorCode": "AGENT_FAILED",
    "steps": [{ "kind": "end", "id": "agent_failed", "errorCode": "AGENT_FAILED" }]
  }
}
```

Compile it like any other plan:

```sh
casen synth support-triage.plan.json --output support-triage.bpmn
casen lint lint support-triage.bpmn --profile deploy
```

Key points:

- **Every tool needs an `id` and a `description`** written for the LLM to read, like briefing a teammate.
- **A tool is either connector-backed (`connector`) or a plain job-worker (`jobType`)** — never both. Search the connector catalog first (`casen connector search`), fall back to `jobType` (with a scaffolded worker) only when no connector exists.
- **A `params[].target` matching a connector value's key overrides it** — the standard way to let the LLM control one field of an otherwise-fixed connector call, as in `notify_slack` above: the channel is fixed, but the message text is supplied by the agent at call time. Give the overridden key a placeholder value in `connector.values`, not a real one.
- **Always give the agent step an error boundary** — an unhandled agent/tool failure needs somewhere to go.
- **Secrets always use `{{secrets.NAME}}`** — never a literal API key or token.

## Deploy-grade validation

`casen lint --profile deploy` includes `agentic/*` rules specific to this pattern:

| Rule | Catches |
|---|---|
| `agentic/tool-not-root` | A tool with an incoming sequence flow (tools must be root nodes) |
| `agentic/tool-no-description` | A tool with no documentation for the LLM to read |
| `agentic/fromai-bad-ref` | A `fromAi()` call whose first argument doesn't reference `toolCall.*` |
| `agentic/no-output-collection` | Missing tool-result aggregation |
| `agentic/limits-missing` | No `maxModelCalls` safety limit |

The `data-flow` category can report spurious "variable never set" findings against the
agent's own provider/model/prompt bindings (a hyphenated model id like `claude-sonnet-5`
can be misread as an arithmetic expression) — this is a known limitation of that heuristic,
not a real issue, and doesn't affect the `deploy` profile.

## Testing without a real LLM call

Scenarios mock the whole agent sub-process as a single job — the dispatcher routes any
job-worker-backed ad-hoc sub-process (this pattern included) through the same job-mock
mechanism as any other task:

```json
{
  "name": "Agent resolves the ticket",
  "mocks": {
    "io.camunda.agenticai:aiagent-job-worker:1": { "outputs": { "agent": { "status": "resolved" } } }
  },
  "expect": { "path": ["triage_agent"], "variables": { "agent": { "status": "resolved" } } }
}
```

```sh
casen test support-triage.bpmn
```

This verifies the process routes correctly through and around the agent step. It does not
exercise the agent's actual tool-calling behavior, prompt quality, or model choice — those
require a real (or sandboxed) LLM run, which is out of scope for `casen test`.

## See also

- [Building Processes with AI](/docs/guides/ai-implement) — the overall plan/synth pipeline
- [`casen connector`](/docs/cli/connector) — searching the catalog for connector-backed tools

---

### AI Decisions

Route a Camunda 8 process on a Cloudflare Clef decision model — typed yes/no, choice and score answers with calibrated probabilities, through one element template.

Source: https://bpmnkit.com/docs/guides/ai-decisions

An [AI agent](/docs/guides/ai-agents) writes text and decides which tools to call. Often a
process step needs less than that: one bounded answer that a gateway can branch on. Which team
gets this ticket? Is this request urgent? How bad is the impact?

A **decision model** answers exactly that kind of question. Cloudflare's
[Clef](https://blog.cloudflare.com/clef-decision-models/) models do not generate text. They
score the options you define in one pass and return a typed answer with a probability for each
option. A gateway can then route on the answer, and route on how sure the model is.

| Step needs | Use |
|---|---|
| Fixed rules over known inputs | A DMN decision (business rule task) |
| A judgement over free text, images or messy data, with a bounded answer | **A decision model** (this guide) |
| Open-ended work: write, research, call tools in a loop | An [AI Agent](/docs/guides/ai-agents) |

## The template

`@bpmnkit/connectors` bundles **Cloudflare Clef Decision**
(`io.bpmnkit.connectors.CloudflareClef.v1`). It is an element template for a service task that
runs on Camunda's REST connector (`io.camunda:http-json:1`), so any cluster with the connector
runtime can run it. You do not deploy a job worker.

To set it up on a cluster and test it step by step, follow the how-to
[Route a Camunda 8 process on a Cloudflare Clef decision](/blog/cloudflare-clef-decisions-camunda).

| Field | Key | Notes |
|---|---|---|
| API token | `authentication.token` | Default `{{secrets.CLOUDFLARE_API_TOKEN}}`. Needs Workers AI permission. |
| Account ID | `accountId` | Default `{{secrets.CLOUDFLARE_ACCOUNT_ID}}`. |
| Model | `model` | `clef` (more accurate, has a vision encoder) or `clef-flash` (lower latency). Sets the URL and the body's `model` together. |
| State | `body.state` | Required. FEEL. What the model evaluates: text, or a context or list. |
| Questions | `body.questions` | Required. FEEL context of 1 to 64 questions, keyed by id. |
| Images | `body.images` | Optional. FEEL list of up to 4 base64 data URLs (PNG, JPEG, WebP). |
| Result expression | `resultExpression` | Default `={clef: response.body.result.answers}`. |

Before you deploy, create the secrets `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in the
cluster's connector secrets.

## Questions and answers

Each question has a `type` and `instructions`. Answers come back under the same ids. With the
default result expression, the answer to question `team` is in `clef.team`.

| Type | `criteria` | Answer |
|---|---|---|
| `noul` (yes/no) | Optional `{"true": …, "false": …}` | `noul`: probability of yes, 0 to 1 |
| `choice` | Required. Context of 2 to 255 options: id → description | `choice`: the option id. `probabilities` per option. `confidence`. |
| `score` | Required. List of 2 to 10 levels, lowest first | `score`: probability-weighted level from 0, can fall between levels. `legend`, `probabilities`, `confidence`. |

```feel
={
  "urgent": {"type": "noul", "instructions": "Is this support request urgent?"},
  "team": {
    "type": "choice",
    "instructions": "Which team should handle this request?",
    "criteria": {
      "billing": "Payments, invoices and refunds",
      "technical": "Outages, errors and configuration",
      "sales": "Plans and upgrades"
    }
  },
  "severity": {
    "type": "score",
    "instructions": "How severe is the customer impact?",
    "criteria": ["No impact", "Minor", "Major", "Critical"]
  }
}
```

The answers for these questions look like this:

```json
{
  "urgent": { "type": "noul", "noul": 0.94 },
  "team": {
    "type": "choice",
    "choice": "technical",
    "probabilities": { "billing": 0.06, "technical": 0.91, "sales": 0.03 },
    "confidence": 0.88
  },
  "severity": {
    "type": "score",
    "score": 2.7,
    "legend": { "0": "No impact", "1": "Minor", "2": "Major", "3": "Critical" },
    "probabilities": { "0": 0.01, "1": 0.04, "2": 0.2, "3": 0.75 },
    "confidence": 0.71
  }
}
```

## Example: triage a support ticket

This process asks the three questions above about a ticket. It pages on-call for an urgent
technical ticket. It sends a ticket to a person when the model is not sure which team should
have it. It queues the remaining tickets by team. The full source is
`apps/examples/src/07-ai-ticket-triage-clef.ts`.

```typescript
import { applyConnectorTemplate } from "@bpmnkit/connectors"
import { Bpmn } from "@bpmnkit/core"

const triage = applyConnectorTemplate("io.bpmnkit.connectors.CloudflareClef.v1", {
  model: "clef-flash",
  "body.state": "={subject: ticket.subject, body: ticket.body, plan: customer.plan}",
  "body.questions": QUESTIONS, // the FEEL context above
})
if (triage.problems.length > 0 || !triage.serviceTask) throw new Error(triage.problems[0]?.message)

const definitions = Bpmn.createProcess("TicketTriage")
  .withAutoLayout()
  .startEvent("start", { name: "Ticket Received" })
  .serviceTask("triage", { ...triage.serviceTask, name: "Triage Ticket" })
  .exclusiveGateway("route", { name: "Route Ticket" })
  .branch("incident", (b) =>
    b
      .condition('=clef.team.choice = "technical" and clef.urgent.noul >= 0.8')
      .serviceTask("pageOncall", { name: "Page On-Call", taskType: "pagerduty-alert" })
      .endEvent("endPaged"),
  )
  .branch("unsure", (b) =>
    b
      .condition("=clef.team.confidence < 0.6")
      .userTask("manualTriage", { name: "Triage by Hand", formId: "manual-triage-form" })
      .endEvent("endManual"),
  )
  .branch("billing", (b) =>
    b
      .condition('=clef.team.choice = "billing"')
      .serviceTask("billingQueue", { name: "Queue for Billing", taskType: "billing-queue" })
      .endEvent("endBilling"),
  )
  .branch("other", (b) =>
    b
      .defaultFlow()
      .serviceTask("supportQueue", { name: "Queue for Support", taskType: "support-queue" })
      .endEvent("endSupport"),
  )
  .build()

const xml = Bpmn.export(definitions)
```

The exclusive gateway takes the first flow whose condition is true, in the order above. An
urgent incident is paged even when the team answer is not certain.

Set the confidence threshold from your own data. Start with a value that sends a good share of
tickets to a person. Look at what the people decide, then lower the threshold.

## Test the routing

In a test, mock the REST connector's job type with the variables that the result expression
writes. You can then test each branch without a call to Cloudflare:

```typescript
import { createProcessTest } from "@bpmnkit/engine/testing"

const t = await createProcessTest({ bpmn: xml })
t.mockJob("io.camunda:http-json:1", {
  result: {
    clef: {
      urgent: { type: "noul", noul: 0.2 },
      team: { type: "choice", choice: "billing", probabilities: {}, confidence: 0.41 },
      severity: { type: "score", score: 1, legend: {}, probabilities: {}, confidence: 0.8 },
    },
  },
})
const run = await t.start("TicketTriage", { ticket: { subject: "Refund", body: "…" } })
// run is waiting at "manualTriage"
```

`apps/examples/tests/ticket-triage-clef.process.test.ts` tests all four branches.

## Use the template in the editor

In the BPMN Kit [editor](/editor), select a service task and pick **Cloudflare Clef Decision**
in the **Connector** list. The panel then shows the template's fields.

## Use the template in Camunda Modeler

To use the template in Desktop Modeler or Web Modeler, write it to a JSON file:

```typescript
import { writeFileSync } from "node:fs"
import { getTemplate } from "@bpmnkit/connectors"

const clef = getTemplate("io.bpmnkit.connectors.CloudflareClef.v1")
writeFileSync(".camunda/element-templates/cloudflare-clef.json", JSON.stringify(clef, null, 2))
```

The template is in the **AI decisions** category of the template chooser.

## Limits

These limits are from Cloudflare's model page:

- 1 to 64 questions for each call. A `choice` has 2 to 255 options. A `score` has 2 to 10 levels.
- The context window is 64k tokens. Long text state is truncated to fit.
- Images: 4 at most, 4 MiB each, 8 MiB in total. Data URLs only. Remote URLs are not accepted.
- A failed call (for example HTTP 401 or 429) fails the job. The template's retries and retry
  backoff apply. To raise a BPMN error instead, set the error expression.

---

### Claude Code Plugin

Install the bpmnkit plugin for Claude Code to get AI-first BPMN development and operations — generate diagrams, wire connectors, deploy, and resolve incidents from natural language.

Source: https://bpmnkit.com/docs/guides/claude-code-plugin

The bpmnkit Claude Code plugin adds BPMN-aware slash commands, autonomous agents, and
ambient quality hooks directly into Claude Code. It's **CLI-first**: every skill drives
`casen` via Bash — no MCP server, no proxy daemon. Every process is authored as a
`ProcessPlan` JSON file and compiled deterministically by `casen synth`; no skill ever
writes BPMN XML by hand.

## Prerequisites

Install the BPMNKit CLI globally:

```sh
npm install -g @bpmnkit/cli
```

That's it — nothing else needs to be running.

## Installation

### Local (development or team)

```sh
claude --plugin-dir ./plugins-claude/bpmnkit-claude
```

Or add to your project's `.claude/settings.json`:

```json
{
  "plugins": [
    { "path": "./plugins-claude/bpmnkit-claude", "scope": "project" }
  ]
}
```

### Via marketplace

```sh
/plugin marketplace add github:bpmnkit/bpmnkit
/plugin install bpmnkit
```

## Configuration

When the plugin is enabled, Claude Code prompts for two optional values:

| Config key | Description |
|---|---|
| `camunda_endpoint` | Camunda 8 REST API endpoint (leave blank for local Reebe) |
| `camunda_token` | Camunda 8 OAuth2 token (leave blank for local Reebe) |

Leave both blank to use the local [Reebe engine](/docs/cli/casen#local-engine-reebe).

---

## Skills

### `/bpmnkit:implement <description>`

The main entry point — natural language to a compiled, tested BPMN process.

```
/bpmnkit:implement order fulfillment with payment and inventory check
/bpmnkit:implement employee onboarding process with HR approval
```

Resolves connectors, writes a `ProcessPlan`, compiles it with `casen synth`, tests it,
scaffolds any missing workers, and asks where to deploy.

---

### `/bpmnkit:extend <file> <change request>`

Extend an existing process from a natural-language change.

```
/bpmnkit:extend order-fulfillment.bpmn add a timeout boundary on the payment step
```

Lifts the process to plan form (`casen plan extract`), writes a small delta plan, and
merges it in (`casen synth --merge`) — the summary is at the element level, not an XML diff.

---

### `/bpmnkit:agent [file] <description>`

Design and add a Camunda AI Agent Sub-process.

```
/bpmnkit:agent add a support-triage agent with tools: search KB (http), escalate to human (user task)
```

Works out the provider/model, prompts, and tools (each mapped via connector search or an
existing worker job type), then compiles and mock-tests the agent step. See
[AI Agents](/docs/guides/ai-agents) for the full pattern.

---

### `/bpmnkit:connect <file> <step> <service>`

Wire an existing plan step to an external system via a Camunda connector template.

```
/bpmnkit:connect order-fulfillment.bpmn notify_ops slack
```

---

### `/bpmnkit:review [file.bpmn]`

Run the full static analyzer and report deploy-readiness.

```
/bpmnkit:review
/bpmnkit:review order-fulfillment.bpmn
```

Reports findings grouped by severity and ends with an explicit "Deploy-ready: yes/no" verdict.

---

### `/bpmnkit:test [file.bpmn]`

Run scenario tests and report path/branch coverage.

```
/bpmnkit:test
/bpmnkit:test order-fulfillment.bpmn
```

---

### `/bpmnkit:deploy [file.bpmn] [--local|--camunda]`

Gate on deploy-readiness, then deploy to local Reebe or Camunda 8.

```
/bpmnkit:deploy
/bpmnkit:deploy order-fulfillment.bpmn --camunda
```

---

### `/bpmnkit:instances [process-id] [--active|--failed]`

List running process instances.

```
/bpmnkit:instances
/bpmnkit:instances order-process --failed
```

---

### `/bpmnkit:incidents [--process-id X]`

List open incidents with suggested resolution actions.

```
/bpmnkit:incidents
/bpmnkit:incidents --process-id order-process
```

---

## Reference docs

Every skill reads the relevant reference doc before authoring a plan:

| File | Contents |
|---|---|
| `references/plan-format.md` | The `ProcessPlan` JSON schema + annotated, tested examples |
| `references/connectors.md` | The bundled connector catalog index |
| `references/agentic.md` | The AI Agent Sub-process pattern, binding keys, a full example |
| `references/feel.md` | FEEL syntax crib sheet + the `"="`-means-expression convention |
| `references/modeling-style.md` | Camunda naming/structure conventions |

---

## Agents

### `process-builder`

Builds a complete BPMN process end-to-end from a description. Invoke directly:

```
Build me an invoice approval process for accounts payable
```

**What it does:**

1. Asks clarifying questions (error paths, user tasks, deploy target)
2. Checks domain patterns (`casen pattern list`/`get`)
3. Resolves connectors, writes the plan
4. Compiles it with `casen synth`
5. Shows a preview and **waits for your approval**
6. Tests the process, fixing failures by adjusting the plan
7. Scaffolds a worker stub for every job type with no connector
8. Gates on `casen lint --profile deploy`, then deploys to the chosen target
9. Reports the process ID, files created, and next steps

---

### `incident-resolver`

Triages and resolves open Camunda incidents. Invoke directly:

```
Investigate and resolve the open incidents
```

**What it does:**

1. Fetches all open incidents (`casen incident list`)
2. Groups by process + error type, sorted by count
3. Investigates root cause per group
4. **Proposes a fix and waits for your approval** before executing
5. Executes approved fixes (retry jobs, resolve incidents, migrate instances)
6. Verifies the count dropped
7. Reports a resolution summary

---

## Ambient Hooks

The plugin installs two background hooks:

| Hook | Trigger | What it does |
|---|---|---|
| SessionStart | Every Claude Code session | Checks `casen` is installed |
| PostToolUse | After any Write or Edit | Silently lints any `.bpmn` file that was written |

The PostToolUse hook means every `.bpmn` file you (or Claude) writes is automatically
checked against the BPMNKit optimizer — zero extra steps.

---

## No MCP server required

Unlike earlier versions of this plugin, none of the skills above call an MCP tool — they
call `casen` directly via Bash. The separate `@bpmnkit/proxy` MCP server (`bpmn-aikit`)
still exists for Claude Desktop, Cursor, or other MCP-only hosts, but it's unrelated to
this plugin.

---

### Drop — Share & Co-edit

Turn a BPMN, DMN or Camunda Form file — or a FEEL expression and the variables it reads — into a link anyone can open, watch live, comment on, and edit one writer at a time. No account, no modeler install, no Camunda cluster.

Source: https://bpmnkit.com/docs/guides/drop

[BPMN Kit Drop](/drop) is the shortest path between a diagram on your machine and the
person who needs to look at it. Drag a file onto the page, get a short link back, send it.
Whoever opens the link sees the diagram rendered in their browser — no account, no modeler
install, and no Camunda cluster anywhere in the story.

It is also where a review happens. A drop is not frozen: anyone with the link can comment
on an element and @mention the people reviewing with them, take the edit baton and change
the diagram while everyone else watching sees the change arrive, and a shared FEEL
statement can be opened, run against different values, and saved back.

## Sharing a file

Open <https://bpmnkit.com/drop> and drop a file onto the page — the whole page is the
target — or paste one from the clipboard. `.bpmn`, `.dmn`, `.form` and `.feel` are all
rendered; `.xml` and `.json` are accepted and sniffed for the kinds above.

| Limit | Value |
| --- | --- |
| Files per drop | 20 |
| Size of a single file | 900 KB |
| Total per drop | 5 MB |
| Retention | 90 days after the last view or edit |

The share id is 11 base58 characters — about 64 bits, so a drop is unguessable and
unlistable, but it is **not** access-controlled: anyone holding the link can view the
diagram and take a turn editing it. Treat a drop the way you would treat an unlisted link,
not the way you would treat a private repository.

You can also start a drop from a diagram you just drew rather than a file you already had:
the [browser editor](/editor) has **Share as a drop** in its main menu, which uploads the
open diagram through the same endpoint and the same checks.

### From the command line

A drop is a plain HTTP upload, so `curl` works:

```sh
curl -s -X POST https://bpmnkit.com/drop/api/drops \
  -F files=@order-process.bpmn
# → { "shareId": "7Fq2mKd9xTs", "url": "https://bpmnkit.com/drop/7Fq2mKd9xTs", "files": [...] }
```

And the stored file comes back either as uploaded or as the parsed model:

```sh
curl -s https://bpmnkit.com/drop/<shareId>/manifest.json
curl -s "https://bpmnkit.com/drop/<shareId>/f/order-process.bpmn"                # original bytes
curl -s "https://bpmnkit.com/drop/<shareId>/f/order-process.bpmn?format=json"    # @bpmnkit/core model
```

A FEEL statement is a file like any other, so the same upload carries one:

```sh
echo '{"expression":"amount > limit","context":{"amount":90,"limit":50}}' \
  | curl -s -F "files=@-;filename=condition.feel" https://bpmnkit.com/drop/api/drops
```

## Sharing a FEEL expression

A gateway condition or a decision-table entry is unreadable on its own: `order.amount * (1
+ vat)` says nothing until you know what `order` and `vat` were. So a FEEL drop carries
both halves — the expression **and** the context it runs against — and the share page
evaluates them in the reader's browser rather than showing a value you typed in by hand.

Three ways in, all producing the same thing:

- **The composer on [/drop](/drop).** Two boxes and a result that updates as you type,
  then **Get a share link**.
- **The [FEEL playground](/feel-functions).** **Share as a drop** posts whatever is in the
  expression and context boxes.
- **A `.feel` file.** Drop or `curl` it like any other file.

A `.feel` file is either the bare expression:

```text
if risk.score < 40 then "approve" else "refer to underwriting"
```

or a JSON document, which is what the composer and the playground post and what a drop
stores:

```json
{
  "expression": "if risk.score < 40 then \"approve\" else \"refer to underwriting\"",
  "context": { "risk": { "score": 22, "band": "low" } },
  "mode": "expression"
}
```

`mode` is `"expression"` (the default) or `"unary-tests"`. In `unary-tests` mode the
statement is read the way a decision-table input entry is, and the value under test is
whatever the context bound to `?`:

```json
{ "expression": "[18..65]", "context": { "?": 30 }, "mode": "unary-tests" }
```

A bare expression is stored as the document it became, so the **Original** download always
round-trips back through the same parser. Expressions that do not parse are refused at
upload, exactly as unparseable BPMN is — a link that renders a syntax error is not worth
sending.

### Trying it with your own numbers

The reason to open somebody else's expression is usually to run it against your own data:
change the amount, see whether the gateway still goes the way they said it does. So the
share page has an **Edit** button for a statement too, and it opens the same two boxes the
composer has, on whatever the drop currently says. Everything you type there stays in your
browser — it evaluates as you type, and the link is untouched until you press a button that
says otherwise:

- **Save to this drop** writes your statement back to the link, so everyone opening it
  afterwards sees the new one. The statement it replaces becomes a milestone in the
  [version log](#reviewing-it-together), and the expression the drop was uploaded with is
  still there as **Original**, as always.
- **Share as new** posts what is in the boxes as a drop of its own and takes you there. The
  original link is left exactly as it was — this is the way out when you were only playing,
  or when the drop is one you may not rewrite.
- **Reset** puts the drop's own statement back in the boxes.

A statement is not edited through the baton: there is no op vocabulary for two boxes of
text, and no live replay to watch, so nothing is claimed and nothing is locked. What
protects the drop instead is the save itself. A save carries the hash of the statement the
page opened, and one made against a statement that has since been replaced is refused with
what the drop says now — so two people editing the same link cannot quietly overwrite each
other, and a reader who sees that message can reload, or keep theirs with **Share as new**.
Where the deployment configures Turnstile, the challenge is on the save and not on opening
the editor: trying an expression out is never worth a challenge, and writing to somebody
else's link is.

## Reviewing it together

Everything below happens on the share page itself — there is nothing to install on either
end.

**Live presence.** The topbar counts the people who have the drop open, and says when one
of them is editing. A diagram moving under a reader's eyes is only unsettling when nothing
on the page explains it.

**One writer at a time.** Editing is a baton, not a merge. Press **Edit** to claim it and
the diagram becomes editable for you and stays live for everyone else; press **Done** to
hand it back. A second person pressing Edit while you hold it is told who has it. There is
no conflict resolution because there is never a second writer to conflict with.

**No save button.** Changes persist as you make them, so there is no moment at which a
reviewer can lose work by closing the tab — and none at which they can be asked whether
they meant it. That is what makes the version log below load-bearing rather than a nicety.

**Asking the AI while you edit.** Where the deployment has AI changes on (a closed beta,
behind an access code), **Ask AI** opens a chat beside the editor. Say what to change — select
elements first to make the request about them — and the change is made in the editor with the
layout kept, as one edit that **Undo** reverts. A diagram drafted with *Describe a process* on
the Drop landing page has **Open in editor**: it is stored as a drop like a share link, and
opens straight into the editor with this chat, so you can keep refining it there.

**Version history.** Every file keeps the original it was uploaded as, pinned and never
overwritten, plus its ten most recent milestones. Repeated saves inside an hour collapse
into one milestone, and a new editing session always starts its own, so a stranger editing
at 10:45 cannot overwrite the previous editor's 10:30 state. Restoring **appends**: the
state being replaced becomes a milestone first, so restoring can never be the thing that
loses work. Undoing a restore is another restore.

**Visual diff.** Two drops can be put side by side at `/drop/<before>/diff/<after>`: added,
removed, changed and *moved* elements marked on synchronised canvases, with pan and zoom
locked together. The same diff is available offline as
[`casen diff bpmn`](/docs/cli/diff) and as a plugin in `@bpmnkit/plugins`.

**Comments.** Press **Comments** to open the review panel. With it open, click an element
on the diagram to comment on that element, or just write to comment on the file as a
whole. DMN, form and FEEL files take whole-file comments only. Each element with open
threads gets a small numbered marker on the canvas; click it to jump to its threads.
Threads take replies, and anyone who has commented on the drop can **Resolve** a thread or
**Reopen** it. New comments, edits and resolutions reach everyone who has the drop open
as they happen.

A comment is anchored by the element's id, not by its position. It stays with the element
when the element moves, and survives any number of edits. If a later edit deletes the
element, the comment is still listed, marked **on a removed element** with the name the
element had when the comment was written. While you preview an older version from
**History**, the same label reads **not in this version**.

**@mentions.** Type `@` in a comment to pick from the names this drop has seen: the people
who have it open now and everyone who has commented on it. A mentioned name is highlighted
in the comment. If the mentioned person has the drop open, a notice appears at the top of
their page with a button that opens the thread. Drop has no accounts and stores no email
addresses, so **a mention sends no email and no push notification**. Someone who does not
have the drop open sees the mention the next time they open it. If it matters, send them
the link yourself.

**Who you are, without an account.** Your display name is whatever you type into the
comment box. The browser remembers it and shows it to the other people viewing the drop.
Nothing checks it, so two people can both call themselves Anna. Your first comment on a
drop gives your browser a private key for that drop, and the server stores only a hash
of it. That key is what lets you edit or delete **your own** comments, and nobody else's.
It lives in this browser only: clear the site data, or change browsers, and your earlier
comments can no longer be edited or deleted from there. A deleted comment that has replies
leaves a "Comment deleted" placeholder, so the replies still make sense.

Comments follow the same abuse rules as edits. Where the deployment configures Turnstile,
your first comment on a drop needs one challenge, and your later comments on it do not.
Each address can make 60 comment writes an hour. A drop holds at most 500 comments, and a
comment is at most 2,000 characters. A drop whose content is on the ban list takes no new
comments. The demo drop and drops an operator has pinned are read-only for comments as
well as for edits. Comments are deleted with their drop: when it expires, or when an
operator removes it.

Diagram editing is limited to BPMN files with a single process — the editor handles one
process at a time — and the built-in demo drop is read-only, though **Edit a copy** will
upload it as a drop of your own. A FEEL statement is edited differently and on its own
terms; see [trying it with your own numbers](#trying-it-with-your-own-numbers) above.

### Rate limiting the edit baton

Because a drop is editable by anyone holding the link, claiming the baton can be put behind
a [Turnstile](https://developers.cloudflare.com/turnstile/) challenge — one challenge per
editing session, not per keystroke. It is invisible to somebody who takes the baton once and
edits for half an hour, and a real cost to a script that wants to rewrite every drop it can
find. On a self-hosted deployment it is configuration (`TURNSTILE_SITE_KEY` and
`TURNSTILE_SECRET`); with neither set, claims are not challenged.

## Running your own

Drop is a single Cloudflare Worker in the monorepo (`apps/drop`), MIT-licensed like
everything else. Files live in D1 as the typed `@bpmnkit/core` model alongside the
byte-faithful original; presence and live editing are a Durable Object per share.

```sh
pnpm --filter @bpmnkit/drop build
wrangler d1 migrations apply bpmnkit-drop --local
wrangler dev --local --port 8787 \
  --var DROP_ADMIN_TOKEN:devtoken --var REPORT_IP_SALT:devsalt
```

That runs the Worker, D1 and the Durable Object in a local simulator, so the whole app works
offline with no Cloudflare account. For a real deployment,
`pnpm --filter @bpmnkit/drop provision` is an idempotent script that creates the database,
applies the migrations, builds the client bundles and deploys the Worker; re-running it
skips whatever is already in place. See `apps/drop/DEPLOY.md` for the full runbook.

## What Drop is not

- **Not a permission system.** Link-holders are editors and commenters. If a diagram
  should not be editable by whoever it reaches, do not put it in a drop.
- **Not a notification service.** A mention reaches someone only if they have the drop
  open. There is no email, no inbox, and no account to send one to.
- **Not storage.** A drop expires 90 days after it was last touched, and the version log
  holds eleven states, not every state.
- **Not a modeler.** It renders and edits one process at a time. For authoring, use the
  [browser editor](/editor), the [VS Code extension](/docs/guides/vscode) or the
  [builder API](/docs/packages/core).

---

### VS Code Extension

View, edit, compare and analyse BPMN, DMN and Camunda Form files inside VS Code — the same renderer, linter and engine the rest of BPMN Kit uses, with no bpmn.io and no round-trip rewrites of your XML.

Source: https://bpmnkit.com/docs/guides/vscode

**BPMN Kit for VS Code** puts the toolkit where the code already is. It renders `.bpmn`,
`.dmn` and `.form` files, reports the same findings `casen lint` reports, compares a diagram
against `HEAD`, runs the process without a cluster, and edits the file without reformatting
it.

The renderer is [`@bpmnkit/canvas`](/docs/packages/canvas), the same from-scratch BPMN 2.0
implementation the website and the browser editor use. There is no bpmn.io anywhere in the
extension, which is the point: the files it shows you are the files git has, byte for byte.

## Installing

Every version is attached as a `.vsix` to a
[GitHub Release](https://github.com/bpmnkit/bpmnkit/releases?q=vscode-v) tagged
`vscode-v<version>`. Download it and install it with **Extensions → … → Install from VSIX…**,
or from a terminal:

```sh
code --install-extension bpmnkit-<version>.vsix
```

The same release workflow publishes to the Visual Studio Marketplace and Open VSX as
`bpmnkit.bpmnkit`; those listings are being set up, and this page will link them once they
are live.

To build it yourself from the monorepo:

```sh
git clone https://github.com/bpmnkit/bpmnkit
cd bpmnkit && pnpm install
pnpm turbo build --filter bpmnkit...
pnpm --filter bpmnkit package     # → apps/vscode/bpmnkit.vsix
```

It activates on a workspace containing a `.bpmn` file, and requires VS Code 1.90 or newer.

## What it does

### Preview beside the source

`.bpmn`, `.dmn` and `.form` all render, with a minimap and zoom for BPMN. The preview
follows the buffer as you type rather than on save, and when the XML is momentarily
unparseable it keeps the last drawing that worked rather than blanking.

The text editor stays the default for all three file types. Open the diagram with
**BPMN Kit: Open Diagram to the Side**, with *Reopen Editor With…*, or make it your default
through `workbench.editorAssociations`.

### Editing that leaves a readable diff

The diagram editor is a **text** custom editor: it edits the same `TextDocument` a text
editor would open. The file is dirty when the document is, <kbd>Ctrl</kbd>+<kbd>S</kbd>
saves it, hot exit restores it, undo is the editor's own undo, and a text editor open on the
same file is a second view of one document rather than a competing copy. Type in the XML and
the diagram follows; move a box and the XML follows.

Saving writes a diff a reviewer can read. A visual editor normally serialises the whole
model, which reformats the file on the first change and buries one edit in a rewrite of
everything. This one writes the file that was already there: renaming a task changes the
line with the task on it, moving a box changes two numbers, and your indentation, attribute
order and comments come back untouched. Opening a diagram and saving it without editing
anything leaves the file byte for byte. Form files get the same treatment — indentation, key
order and trailing newline all survive.

That behaviour is not extension-specific; it is
[`exportPreserving()`](/docs/packages/core#exportpreservingoriginal-definitions) from
`@bpmnkit/core`, available to anything that writes a model back over a file it parsed.

### Findings in the Problems panel

The same static analysis `casen lint` runs — flow reachability, naming, FEEL syntax, data
flow, Camunda 8 deployability — reported against the element that caused it, so clicking a
problem takes you to the tag rather than to line 1.

The analysis matches the file. A diagram that declares no `modeler:executionPlatform` is not
judged against Camunda 8 deployability, because "this service task has no
`zeebe:taskDefinition`" is not a defect in a diagram that was never going to be deployed to
Zeebe. Turn on `bpmnkit.lint.forceEngineRules` to apply those rules anyway.

A `.bpmnlintrc` in the diagram's folder or above is honoured the way `casen lint` honours it.
When the workspace has `bpmnlint` installed, bpmnlint's own findings, plugin rules included,
appear with source `bpmnlint`. See [bpmnlint Compatibility](/docs/guides/bpmnlint).

A connector task's required inputs are checked against the element templates **this file**
sees: `.camunda/element-templates/` in the diagram's folder and every folder above it up to the
workspace folder, the nearest winning on an id, then the bundled Camunda templates. A diagram in
`a/` is never checked against `b/`'s templates. The extension host reads them itself; no proxy
is needed. An unsaved file has no folder, so only the bundled templates apply. See
[workspace templates](/docs/packages/connectors#workspace-templates).

### A visual diff in Source Control

Right-click a `.bpmn` file in Source Control to see it against `HEAD`, or select exactly two
in the Explorer to compare them with each other. Added, removed, changed and moved elements
are marked on synchronised canvases — a moved element reads as *moved*, not as two unrelated
pictures. The text diff stays where it was; this is a second view of the same change, not a
replacement for the first. The same comparison is available as
[`casen diff bpmn`](/docs/cli/diff) and on a [drop](/docs/guides/drop).

### Run the diagram in the editor

[`@bpmnkit/engine`](/docs/packages/engine) is a BPMN engine written in TypeScript, so the
preview does not need a cluster to execute what is on screen. Press **Run** and watch tokens
move; press **One Step** to advance the instance one element at a time, reading the variables
as they change. Nothing is deployed and nothing leaves your machine.

### A FEEL playground on your selection

Select an expression anywhere in the XML and open the playground: it comes up pre-filled,
with a context you can edit and the result evaluated as you type. Unary tests too, for
decision-table input entries.

### Deploy against your own clusters

Deployment targets come from `casen`'s profile store — the same file
[`casen profile create`](/docs/cli/casen#connection-profiles) writes — so there is no second
place to configure a cluster and no credentials in your workspace settings:

```sh
casen profile create staging --base-url https://<cluster>.camunda.io/<id> \
  --auth-type oauth --client-id … --client-secret …
```

Every `c8` profile then appears in the extension. Deploy the open file, or deploy and start
an instance with variables; the instance key comes back in a notification. Deploy-and-start
also offers the payloads it finds in `.camunda/payloads/*.json`, walking up from the diagram,
so the inputs a process is always tried with are a pick rather than a paste.

Credentials are read only to sign the request — nothing in the extension stores, displays or
logs them.

### Copy the diagram as text

For a code review, where a picture cannot go. **BPMN Kit: Copy Diagram as ASCII** renders the
layout into a fenced block that pastes into a pull request, an issue or a commit message,
dedented so the diagram is not mostly margin.

## Commands

| Command | Where |
| --- | --- |
| **BPMN Kit: Open Diagram to the Side** | Editor title bar, command palette |
| **BPMN Kit: Compare Diagram with HEAD** | Source Control context menu, editor title bar |
| **BPMN Kit: Compare Diagrams Visually** | Explorer, with exactly two `.bpmn` files selected |
| **BPMN Kit: Open FEEL Playground** | Command palette — pre-filled from the selection |
| **BPMN Kit: Copy Diagram as ASCII** | Editor title bar, Explorer, command palette |
| **BPMN Kit: Deploy to Camunda 8** | Command palette |
| **BPMN Kit: Deploy and Start Instance** | Explorer, command palette |

## Settings

| Setting | Default | What it does |
| --- | --- | --- |
| `bpmnkit.lint.enabled` | `true` | Report findings in the Problems panel |
| `bpmnkit.lint.run` | `onType` | `onType` or `onSave` |
| `bpmnkit.lint.forceEngineRules` | `false` | Apply Camunda 8 rules to an engine-neutral diagram |
| `bpmnkit.lint.bpmnlintrc` | `true` | Honour the nearest `.bpmnlintrc`, and run the workspace's bpmnlint if installed |
| `bpmnkit.viewer.grid` | `true` | Dot grid behind the diagram |
| `bpmnkit.viewer.minimap` | `true` | Minimap in the BPMN viewer |
| `bpmnkit.simulation.enabled` | `true` | Offer step-through simulation in the preview |
| `bpmnkit.editing.enabled` | `true` | Let the diagram editor change the file |

Findings are reported for `.bpmn` files that are open; a file the editor has not loaded is
not analysed, same as every other linter in VS Code. Set `bpmnkit.editing.enabled` to `false`
for the same editors with editing switched off, when a diagram should be openable with no
chance of changing it.

## Support

The extension is pre-1.0 and community-supported, developed in the open in the
[monorepo](https://github.com/bpmnkit/bpmnkit) alongside the packages it is built from.
Minor versions may change behaviour before 1.0: the features above will not disappear, but
setting names and command titles may still move. Bugs and requests go to
[GitHub issues](https://github.com/bpmnkit/bpmnkit/issues). MIT-licensed, like everything
else in the repository.

---

### bpmnlint Compatibility

Keep your .bpmnlintrc. casen lint and the VS Code extension read it, map bpmnlint's rules onto BPMN Kit's findings, and run your project's own bpmnlint for bpmnlint-plugin-* rules. Includes the rule-by-rule mapping table.

Source: https://bpmnkit.com/docs/guides/bpmnlint

Teams coming from bpmn.io usually already have a lint configuration: a `.bpmnlintrc` next to
their diagrams, bpmnlint's built-in rules, and maybe a `bpmnlint-plugin-*` package or two.
BPMN Kit reads that file. You do not need to translate it.

`casen lint` and the [VS Code extension](/docs/guides/vscode) look for `.bpmnlintrc` in the
diagram's folder and then in each parent folder, and use the first one they find. What happens
next depends on whether your project has bpmnlint installed.

## Two ways a `.bpmnlintrc` is honoured

**Your project has bpmnlint installed** (`bpmnlint` and `bpmn-moddle` are in the
`node_modules` next to the `.bpmnlintrc` or above it). BPMN Kit loads that bpmnlint and runs
your configuration with it. Presets, `plugin:` configs, third-party plugin rules and rule
options all resolve exactly as they do for the `bpmnlint` command. The findings appear under
the `bpmnlint` category, named by their rule. BPMN Kit then drops its own findings for every
rule bpmnlint just ran, so no problem is reported twice.

**bpmnlint is not installed.** BPMN Kit applies the configuration to its own analysis:

- A finding that is BPMN Kit's equivalent of a bpmnlint rule (see the table below) takes the
  level your config gives that rule. `"off"` removes it.
- A rule your config enables, and that BPMN Kit implements natively for compatibility, runs.
  These rules never run without a `.bpmnlintrc`, so the default `casen lint` report does not
  change.
- A rule your config does not mention keeps BPMN Kit's default. The `.bpmnlintrc` overrides
  BPMN Kit where the two overlap. It does not switch off BPMN Kit's other checks (FEEL syntax,
  data flow, Camunda 8 deployability and so on).
- A plugin rule (`acme/no-foo`), an unknown rule, or a `plugin:` config in `extends`
  cannot be applied without bpmnlint. BPMN Kit says so rather than ignoring it silently. The
  exception is `bpmnlint-plugin-camunda-compat`: BPMN Kit has its own
  [Camunda version check](#camunda-version-compatibility) and uses it in place of the plugin.

bpmnlint is never a dependency of BPMN Kit. It is loaded with a dynamic `import()` from your
project, only when your project has it, the same way editor integrations load a project's
own ESLint.

## `casen lint`

```sh
casen lint lint diagrams/order.bpmn
```

```text
→ Using /work/project/.bpmnlintrc (BPMN Kit's equivalents of its rules).
→ Not applied — no BPMN Kit equivalent: plugin:acme/recommended (a plugin config — install bpmnlint in the project to use it).
→ ⚠ [pattern] [Error_payment] Global error "Error_payment" is not referenced by any element. (global)
→ ✖ [pattern] [End_done] Element "End_done" has no diagram information (BPMNDI). (no-bpmndi)
```

The rule name in parentheses is the bpmnlint rule the finding was reported under. With
bpmnlint installed, the first line reads `(bpmnlint 11.14.0)` and bpmnlint's own findings
appear as `[bpmnlint]`.

| Flag | Effect |
|---|---|
| `--no-bpmnlintrc` | Ignore any `.bpmnlintrc`. The report is the same as without one. |
| `--categories flow,naming` | Leaves out real bpmnlint. Its findings belong to the `bpmnlint` category, so it only runs when `--categories` is not given or includes `bpmnlint`. BPMN Kit's equivalents stand in for it. |
| `--format json` | stdout stays a JSON array of findings. A finding governed by the config has a `bpmnlintRule` field. Notices go to stderr. |

The exit code works as before: the command fails when an error-level finding remains. Your
config can change that in both directions. It can raise a warning to `error`, or lower an
error to `warn`. A `.bpmnlintrc` that is not valid JSON, or has a rule level that is not
`off`, `warn`, `error`, `info` or `0`–`3`, stops the command with the file's path in the
message.

Unlike the `bpmnlint` command, which reads `.bpmnlintrc` from the current directory only,
BPMN Kit starts at the diagram's folder. Running `casen lint` from anywhere therefore gives
the same result. Plugins and `moddleExtensions` resolve from the `.bpmnlintrc`'s folder.

## VS Code

The Problems panel honours the same file, found the same way. A finding from real bpmnlint
shows `bpmnlint` as its source and the rule as its code. A finding BPMN Kit reports under a
bpmnlint rule has the rule name at the end of its message. If some configured rules could not
be applied, one information-level problem at the top of the file lists them. A broken
`.bpmnlintrc` shows as an error there too.

Editing a `.bpmnlintrc` re-analyses the open diagrams. Set `bpmnkit.lint.bpmnlintrc` to
`false` to ignore the file. Only diagrams saved on disk are checked against a `.bpmnlintrc`,
because an untitled buffer has no folder.

## Rule mapping

These are the 28 rules bpmnlint 11.14 ships. All 28 are **exact**: the rule has the same
semantics as bpmnlint's, and BPMN Kit reports the same elements, in the top-level process and
inside embedded, event and ad-hoc sub-processes and transactions. We check this with a test for
each rule, and with a test that runs both linters under `bpmnlint:all` against every `.bpmn`
file in the BPMN Kit repository. That corpus has 43 files: BPMN Kit's own samples and
fixtures, the OMG MIWG test models, and a fixture that puts each rule's violations and
exemptions inside every kind of sub-process. It is still a corpus, so treat it as evidence,
not proof. "Native" marks a check BPMN Kit added for this compatibility layer. It runs only
when your config enables the rule.

For four rules, BPMN Kit's own check looks at a different set of elements, so the native check
**replaces** it while your config sets the rule, at any level. For example, `flow/unreachable`
reports everything that cannot be reached from a start event, and bpmnlint's
`no-implicit-start` reports only elements without an incoming flow. Without a `.bpmnlintrc`,
`casen lint` reports BPMN Kit's own checks as before.

| bpmnlint rule | recommended | BPMN Kit finding | Match | Notes |
|---|---|---|---|---|
| `ad-hoc-sub-process` | error | `flow/ad-hoc-start-end-event` (native) | Exact | |
| `conditional-event` | — | `flow/conditional-event-no-condition` (native) | Exact | |
| `conditional-flows` | error | `feel/missing-condition` (native) | Exact | Replaces `feel/empty-condition`. |
| `end-event-required` | error | `flow/no-end-event`, `flow/sub-process-no-end-event` (native) | Exact | |
| `event-based-gateway` | error | `flow/event-gateway-invalid` (native) | Exact | |
| `event-sub-process-typed-start-event` | error | `flow/event-sub-process-untyped-start` (native) | Exact | |
| `fake-join` | warn | `flow/multi-incoming-task` (native inside sub-processes and for start events) | Exact | |
| `global` | warn | `pattern/global-element` (native) | Exact | |
| `label-required` | error | `naming/missing-label` (native) | Exact | Replaces `naming/unlabeled-task`, `naming/unlabeled-start-event`, `naming/unlabeled-end-event`, `naming/split-gateway-no-label` and `naming/missing-flow-condition`. Lanes are read from the process's first lane set, the one BPMN Kit models. |
| `link-event` | error | `flow/link-event-mismatch` (native) | Exact | |
| `no-bpmndi` | error | `pattern/missing-di` (native) | Exact | |
| `no-complex-gateway` | error | `pattern/complex-gateway` (native) | Exact | |
| `no-disconnected` | error | `flow/disconnected` (native) | Exact | |
| `no-duplicate-sequence-flows` | error | `flow/duplicate-sequence-flow` (native) | Exact | One finding for each duplicate flow, which names the flow, its source and its target. bpmnlint reports these three separately. |
| `no-gateway-join-fork` | error | `flow/mixed-gateway` (native inside sub-processes) | Exact | |
| `no-implicit-end` | error | `flow/implicit-end` (native) | Exact | Replaces `flow/dead-end`. |
| `no-implicit-split` | error | `flow/implicit-split` (native) | Exact | |
| `no-implicit-start` | error | `flow/implicit-start` (native) | Exact | Replaces `flow/unreachable`. |
| `no-inclusive-gateway` | warn | `pattern/inclusive-gateway` (native) | Exact | |
| `no-overlapping-elements` | warn | `pattern/overlapping-elements` (native) | Exact | |
| `single-blank-start-event` | error | `flow/multiple-blank-start-events` (native) | Exact | |
| `single-event-definition` | error | `flow/multiple-event-definitions` (native) | Exact | |
| `standard-size` | — | `pattern/non-standard-size` (native) | Exact | Accepts the same per-type options, for example `["warn", { "bpmn:Task": { "width": 120, "height": 80 } }]`. |
| `start-event-required` | error | `flow/no-start-event`, `flow/sub-process-no-start-event` (native) | Exact | |
| `sub-process-blank-start-event` | error | `flow/sub-process-typed-start` (native) | Exact | |
| `superfluous-gateway` | warn | `flow/redundant-gateway` (native inside sub-processes) | Exact | |
| `superfluous-label` | warn | `naming/superfluous-flow-label` (native) | Exact | |
| `superfluous-termination` | warn | `flow/superfluous-termination` (native) | Exact | |

`bpmnlint:recommended`, `bpmnlint:all` and `bpmnlint:correctness` expand to bpmnlint 11.14's
presets. Rule names are normalised the way bpmnlint normalises them, so
`bpmnlint/label-required` and `label-required` are the same rule.

Rules that have no equivalent without bpmnlint installed:

- **Plugin rules and configs.** Everything from `bpmnlint-plugin-*`, except the
  `bpmnlint-plugin-camunda-compat` rules listed as covered below. Install bpmnlint in the
  project and they run.
- **Unknown rule names.** These are reported as unknown, the same as bpmnlint would report
  them.

Where the native equivalents check connections, they read the sequence flows, not the
`<bpmn:incoming>`/`<bpmn:outgoing>` children. Real bpmnlint reads the children. For files a
modeler wrote, the two are the same. For hand-written XML that leaves the children out,
bpmnlint sees no connections at all, and BPMN Kit sees the flows.

## Camunda version compatibility

Camunda Modeler checks a diagram against the Camunda 8 version it targets. The version is in
`modeler:executionPlatformVersion` on `<bpmn:definitions>`, and the rules come from
`@camunda/linting`, which runs `bpmnlint-plugin-camunda-compat`. BPMN Kit does the same check
itself, as `compat/…` findings in the `deploy` category. It runs in `casen lint`, in `optimize()`, in the editor's lint
panel and in the VS Code extension, on every model that names a Camunda Cloud / Camunda 8
platform and version. A model without them gets no `compat` findings.

```text
✖ [deploy] [tools] Ad-hoc sub-process "Tools" needs Camunda 8.7 or newer; this model targets Camunda 8.6.
✖ [deploy] [notify] Signal end event "Notify" needs Camunda 8.3 or newer; this model targets Camunda 8.2.
✖ [deploy] [wait] Timer intermediate catch event "wait" has timeDuration "5 minutes", which is not an ISO 8601 duration (PT15M).
```

Each finding is `compat/<rule>`, named after the plugin rule it reproduces, and has the
plugin's severity. Three kinds of problem are reported:

- **Something the target version cannot run.** An element or event definition that is newer
  than the target (inclusive gateways 8.1, `bpmn:task` 8.2, escalation and link events 8.2,
  signal events 8.2/8.3, compensation 8.5, ad-hoc sub-processes 8.7, conditional events 8.9),
  or one no version runs (complex gateway, transaction). Also Zeebe extensions and properties:
  `zeebe:properties` (8.1), candidate users, task schedule and `propagateAllParentVariables="false"`
  (8.2), start event forms (8.3), `formId` and collapsed sub-processes (8.4), `zeebe:userTask`
  (8.5), execution listeners, `bindingType`, version tags and task priority (8.6), task listeners
  (8.8), and business ids, job priority and `beforeAll`/`cancel` listeners (8.10). A cron timer
  cycle needs 8.1, and a `timeDate` on a boundary or intermediate event needs 8.3.
- **A property the target version requires.** A job type, called decision or script, a called
  process id, a message name and correlation key, a timer value that parses as ISO 8601 or
  cron, an error code, an escalation code, a signal name, a multi-instance input collection,
  a condition on each non-default flow out of a gateway, and listener types.
- **Something wrong inside a value.** A FEEL built-in newer than the target (`uuid()` and
  `trim()` need 8.6, `from json()` 8.9, from `@camunda/feel-builtins`); a mapping target or
  result variable that is not a variable name; a secret written as `secrets.X`, or as
  `{{secrets.X}}` once 8.10 has `camunda.secrets.X`; a `camunda.secrets.X` reference in a
  string, a list or an `if` branch's context, where 8.10 cannot resolve it; inbound connector
  properties (`messageTtl`, `consumeUnmatchedEvents`, `deduplicationModeManualFlag`) before 8.6;
  a link event with no name, or two link catch events with the same name; duplicate header
  keys on one execution listener (8.10); and a loop of plain tasks, manual tasks and call
  activities with nothing that waits. Agent tools (8.8) are checked too: `fromAi()` only in an
  input mapping of a tool's first element, with a `toolCall.<name>` key and a quoted
  description, and each tool's result mapped to `toolCallResult`. These rules keep the plugin's
  own messages, such as `FEEL function <uuid> requires Camunda >=8.6`.

From 8.2 on, processes that are not marked executable are skipped, as Modeler skips them. A
version newer than the table is checked as the newest version the table has (8.10). Later
versions only remove restrictions.

The version table is data (`CAMUNDA_COMPAT_RULES` in `@bpmnkit/core`), taken from
`bpmnlint-plugin-camunda-compat` 2.61.0 (`@camunda/linting` 3.57.0). BPMN Kit does not
report a problem twice. When a `deploy/*` check already reports it on the same element, only
that finding stays. For example, `deploy/service-task-no-type` stands in for
`compat/implementation`, and when a `.bpmnlintrc` runs bpmnlint's `link-event`,
`flow/link-event-mismatch` stands in for `compat/link-event`.

### With a `.bpmnlintrc`

`extends: "plugin:camunda-compat/camunda-cloud-8-6"` (or the `bpmnlint-plugin-camunda-compat`
spelling, and any `camunda-cloud-1-0` to `camunda-cloud-8-10`) runs this check against 8.6,
whatever version the model names. This also works on a model that names no platform. The
config's rules take the plugin's levels. `camunda-compat/<rule>` entries under `rules` change
the level or turn a rule `off`, and the finding shows the rule name. Like the plugin's configs,
it also turns on `start-event-required`. When your project's own bpmnlint runs the plugin,
BPMN Kit's `compat` findings step aside. `camunda-platform-7-*` configs are not mapped.

### What is covered

| Plugin rules | Coverage |
|---|---|
| `element-type`, `implementation`, `timer`, `called-element`, `message-reference`, `error-reference`, `escalation-reference`, `escalation-boundary-event-attached-to-ref`, `signal-reference`, `no-expression`, `event-based-gateway-target`, `inclusive-gateway`, `loop-characteristics`, `sequence-flow-condition`, `no-multiple-none-start-events`, `collapsed-subprocess`, `io-mapping`, `duplicate-task-headers`, `no-template` | Covered |
| `no-zeebe-properties`, `no-candidate-users`, `no-propagate-all-parent-variables`, `no-task-schedule`, `task-schedule`, `no-signal-event-sub-process`, `start-event-form`, `start-event-form-embedded`, `user-task-form`, `user-task-definition`, `no-zeebe-user-task`, `zeebe-user-task`, `wait-for-completion` | Covered |
| `no-binding-type`, `no-execution-listeners`, `execution-listener`, `duplicate-execution-listeners`, `no-priority-definition`, `priority-definition`, `no-version-tag`, `version-tag`, `ad-hoc-sub-process`, `no-interrupting-event-subprocess`, `no-task-listeners`, `task-listener` | Covered |
| `no-business-id`, `no-execution-listener-headers`, `no-before-all-execution-listener`, `before-all-execution-listener`, `no-cancel-execution-listener`, `cancel-execution-listener`, `no-job-priority-definition` | Covered |
| `subscription` | Covered. A `zeebe:subscription` on the catch element instead of on its `bpmn:message` is an error, as in the plugin. BPMN Kit's builders put it on the message. |
| `feel-compatibility`, `variable-name`, `secrets`, `unresolvable-secret-reference`, `connector-properties`, `duplicate-execution-listener-headers`, `no-loop` | Covered, with the plugin's messages. FEEL is read by BPMN Kit's own parser, so an expression only one of the two parsers accepts can be judged differently. |
| `agent-fromai-contract`, `agent-tool-output-key` | Covered, with the plugin's messages |
| `link-event` | Covered, with the plugin's messages. Where bpmnlint's `link-event` also runs, its `flow/link-event-mismatch` finding stays instead. |
| `executable-process`, `feel`, `agent-tool-documentation` | Reported by an existing finding: `deploy/process-not-executable` (which reports every non-executable process), `feel-syntax/parse-error`, `agentic/tool-no-description` |

All 65 rules of the plugin's `camunda-cloud-*` configs are covered: 62 are reproduced, and
3 are reported by existing findings. Checked against the plugin: the test suite has four
fixture diagrams that trigger all 62 reproduced rules. It compares BPMN Kit's findings with
what the real plugin reported for them under every `camunda-cloud-*` config. The findings
match element for element, and message for message where the table says so. The 25 process templates in `@bpmnkit/patterns` give the same result as the plugin
too.

## From your own code

The configuration and mapping are plain functions in `@bpmnkit/core`, with no filesystem
access, so they work in a browser too:

```typescript
import { Bpmn, lintDiagram, parseBpmnlintConfig, resolveBpmnlintConfig } from "@bpmnkit/core"

const config = resolveBpmnlintConfig(parseBpmnlintConfig(rcText))
const report = lintDiagram(Bpmn.parse(xml), { bpmnlint: config })
report.diagnostics      // governed findings carry `bpmnlintRule`
report.bpmnlintUnsupported // what the config asked for that could not be applied
```

In Node, `@bpmnkit/core/node` finds the file and runs the project's bpmnlint:

```typescript
import { applyBpmnlintConfig, Bpmn, optimize } from "@bpmnkit/core"
import { prepareBpmnlint } from "@bpmnkit/core/node"

const setup = await prepareBpmnlint(filePath, xml) // undefined when no .bpmnlintrc applies
if (setup) {
  const defs = Bpmn.parse(xml)
  const { findings, unsupported } = applyBpmnlintConfig(defs, optimize(defs).findings, setup.config, {
    delegated: setup.delegated, // true when real bpmnlint ran; its reports are in setup.reports
  })
}
```

`BPMNLINT_RULE_MAP` exports the table above as data.

---

### BPMN Diagrams in Markdown

Put real BPMN diagrams in READMEs, Astro, Docusaurus, VitePress and MDX pages — write a fenced ```bpmn or ```bpmn-compact block and @bpmnkit/markdown renders it to inline, themeable, accessible SVG at build time.

Source: https://bpmnkit.com/docs/guides/bpmn-in-markdown

Mermaid has no BPMN, and PlantUML's BPMN is a sketch. `@bpmnkit/markdown` fills the gap for
docs-as-code: write a process as a fenced code block, and the build turns it into a real BPMN
diagram — the same renderer, layout engine and shapes as the rest of BPMN Kit, drawn as inline
SVG with no client-side JavaScript.

This page uses it. The diagram below is this block, rendered when the site was built:

````md
```bpmn-compact title="Order fulfilment"
{
  "id": "order-fulfilment",
  "elements": [
    { "id": "received", "type": "startEvent", "name": "Order received" },
    { "id": "check", "type": "serviceTask", "name": "Check stock", "jobType": "check-stock" },
    { "id": "inStock", "type": "exclusiveGateway", "name": "In stock?" },
    { "id": "ship", "type": "serviceTask", "name": "Ship order", "jobType": "ship-order" },
    { "id": "shipped", "type": "endEvent", "name": "Shipped" },
    { "id": "backorder", "type": "userTask", "name": "Back-order items" },
    { "id": "waiting", "type": "endEvent", "name": "Back-ordered" }
  ],
  "flows": [
    { "id": "f1", "from": "received", "to": "check" },
    { "id": "f2", "from": "check", "to": "inStock" },
    { "id": "f3", "from": "inStock", "to": "ship", "condition": "=available" },
    { "id": "f4", "from": "inStock", "to": "backorder", "isDefault": true },
    { "id": "f5", "from": "ship", "to": "shipped" },
    { "id": "f6", "from": "backorder", "to": "waiting" }
  ]
}
```
````

```bpmn-compact title="Order fulfilment"
{
  "id": "order-fulfilment",
  "elements": [
    { "id": "received", "type": "startEvent", "name": "Order received" },
    { "id": "check", "type": "serviceTask", "name": "Check stock", "jobType": "check-stock" },
    { "id": "inStock", "type": "exclusiveGateway", "name": "In stock?" },
    { "id": "ship", "type": "serviceTask", "name": "Ship order", "jobType": "ship-order" },
    { "id": "shipped", "type": "endEvent", "name": "Shipped" },
    { "id": "backorder", "type": "userTask", "name": "Back-order items" },
    { "id": "waiting", "type": "endEvent", "name": "Back-ordered" }
  ],
  "flows": [
    { "id": "f1", "from": "received", "to": "check" },
    { "id": "f2", "from": "check", "to": "inStock" },
    { "id": "f3", "from": "inStock", "to": "ship", "condition": "=available" },
    { "id": "f4", "from": "inStock", "to": "backorder", "isDefault": true },
    { "id": "f5", "from": "ship", "to": "shipped" },
    { "id": "f6", "from": "backorder", "to": "waiting" }
  ]
}
```

```bash
npm install --save-dev @bpmnkit/markdown
```

## What goes in a block

| Fence | Contents |
|---|---|
| ` ```bpmn ` | BPMN 2.0 XML — a whole `.bpmn` file. If it carries diagram interchange (`<bpmndi:BPMNDiagram>`), that layout is drawn as it is; if the DI is missing or incomplete, the diagram is laid out automatically. |
| ` ```bpmn-compact ` | The [compact JSON format](/docs/getting-started/concepts) that `compactify()` produces and language models write. A single process can skip the `{ "id", "processes": [...] }` wrapper, as above. Always laid out automatically. |
| ` ```bpmn-json ` | An alias of `bpmn-compact`. |

There is no text DSL: the compact JSON already is the short form, and it is the same format
the rest of BPMN Kit and your AI tooling speak.

One fence attribute is read: `title="…"` sets the diagram's accessible name. Without it the
name is the process's `name`, then the first pool's, then the process id.

## Astro

```js
// astro.config.mjs
import { remarkBpmn } from "@bpmnkit/markdown"
import { defineConfig } from "astro/config"

export default defineConfig({
  markdown: { remarkPlugins: [[remarkBpmn, { maxWidth: 760 }]] },
})
```

That covers `.md` content collections and, through `@astrojs/mdx`, `.mdx` pages too. This site
is configured exactly this way.

## Docusaurus

```js
// docusaurus.config.mjs
import { remarkBpmn } from "@bpmnkit/markdown"

export default {
  presets: [
    ["classic", { docs: { remarkPlugins: [remarkBpmn] }, blog: { remarkPlugins: [remarkBpmn] } }],
  ],
}
```

The package is ESM-only; with a CommonJS `docusaurus.config.js`, load it with
`const { remarkBpmn } = await import("@bpmnkit/markdown")` inside an async config function.

## VitePress

VitePress renders Markdown with markdown-it, so use the markdown-it plugin:

```ts
// .vitepress/config.ts
import { markdownItBpmn } from "@bpmnkit/markdown"
import { defineConfig } from "vitepress"

export default defineConfig({
  markdown: { config: (md) => md.use(markdownItBpmn) },
})
```

Every other fence is handed back to the rule that was there before, so VitePress's
highlighting and code groups keep working.

## Next.js MDX, unified, anything remark

```js
// next.config.mjs
import createMDX from "@next/mdx"
import { remarkBpmn } from "@bpmnkit/markdown"

const withMDX = createMDX({ options: { remarkPlugins: [remarkBpmn] } })
export default withMDX({ pageExtensions: ["ts", "tsx", "md", "mdx"] })
```

`remarkBpmn` is an ordinary remark plugin, so `unified().use(remarkParse).use(remarkBpmn)…`
works the same way.

It is a **remark** plugin rather than a rehype one on purpose. At the remark stage the block
is still a Markdown `code` node with its language on it; by the rehype stage a syntax
highlighter has usually turned it into a tree of coloured spans. And it hands the diagram on
as hast elements, not as a raw HTML string, so MDX — which drops raw HTML — renders it too.

## Plain HTML pipelines

If your tool produces HTML and offers no plugin hook, rewrite the HTML afterwards.
`renderBpmnInHtml` replaces every `<pre><code class="language-bpmn…">` block:

```ts
import { renderBpmnInHtml } from "@bpmnkit/markdown"

const page = renderBpmnInHtml(markdownToHtml(source))
```

And for anything else there is the function every adapter wraps:

```ts
import { renderBpmnBlock } from "@bpmnkit/markdown"

const result = renderBpmnBlock(xml, "bpmn", { theme: "auto" })
if (result.ok) writeFileSync("process.svg", result.svg)
else console.error(result.error)
```

## GitHub READMEs

GitHub runs no plugins, so the diagram has to be committed as an image. `bpmnkit-md` does
that for you:

```bash
npx bpmnkit-md README.md
```

Each BPMN block becomes a marked region: an image of the diagram, and the block itself folded
into a `<details>` underneath, so the source stays in the README and stays the thing you edit.

````md
<!-- bpmnkit-md:begin diagrams/order-fulfilment.svg -->
![Order fulfilment](diagrams/order-fulfilment.svg)

<details>
<summary>BPMN source</summary>

```bpmn-compact
{ … }
```

</details>
<!-- bpmnkit-md:end -->
````

Run it again after editing the source and it re-renders the region in place — the command is
idempotent, so it is safe in a pre-commit hook. In CI, `--check` writes nothing and exits 1
when a README or an SVG is out of date:

```bash
npx bpmnkit-md --check README.md docs/*.md
```

| Option | Meaning |
|---|---|
| `--out-dir <dir>` | Where new SVGs go, relative to each Markdown file. Default `diagrams`. A fence attribute `file=path/to.svg` picks one block's path. |
| `--theme auto\|light\|dark` | Default `auto`: the SVG follows the reader's colour scheme, GitHub dark mode included. |
| `--max-width <px>` | Largest width to draw a diagram at. |
| `--check` | Verify only; exit 1 if anything would change. |

`bpmnkit-md file.bpmn` writes `file.svg` next to a standalone diagram. Invalid blocks fail
the command with the line number — a committed picture of an error box helps no one.

## Options

The plugins, `renderBpmnInHtml` and `renderBpmnBlock` take the same options:

| Option | Default | Meaning |
|---|---|---|
| `theme` | `"auto"` | `auto` uses the page's `--bpmnkit-*` tokens when it defines them, and the reader's `prefers-color-scheme` when it does not. `light` / `dark` pin the palette and ignore the page. |
| `maxWidth` | natural size | Largest width in CSS pixels. The diagram still shrinks to fit narrower containers. |
| `title` | process name | The accessible name. A fence's `title="…"` overrides it per block. |
| `link` | off | `({ xml, title }) => href` — adds an "Open in BPMN Kit" link under the diagram, pointing wherever you host an editor. |
| `onError` | `"render"` | `render` draws a readable error box in place of the diagram; `throw` fails the build. |

## Theming

The SVG reads the same tokens as every other BPMN Kit surface — `--bpmnkit-bg` for the
ground, `--bpmnkit-surface` for shape fills, `--bpmnkit-fg` for strokes and labels,
`--bpmnkit-font` for type — each with a light and a dark fallback. A site that defines the
tokens gets a diagram in its own palette; one that does not gets the BPMN Kit palette in the
reader's colour scheme.

The switch is CSS `light-dark()` under `color-scheme: light dark`, written into `style`
attributes rather than a `<style>` element. An inline SVG's `<style>` applies to the whole
page, and Vue templates (VitePress) drop it entirely; attributes have neither problem. It
needs a browser from 2024 or later.

## Accessibility

Every diagram is an `<svg role="img">` labelled by its `<title>` and described by a `<desc>`
that lists the process's named steps in order, so a screen reader announces
"Order fulfilment — BPMN process diagram. Steps: Order received, Check stock, …". In
pre-rendered READMEs, the title is the image's alt text.

## Errors

A block that does not parse does not break the build by default. It renders as a box that
says what went wrong:

```bpmn-compact
{ "id": "typo", "elements": [ { "id": "start", "type": "startEvnt" } ], "flows": [] }
```

The remark plugin also adds the error to the file's messages (`file.messages`), where tools
that report vfile warnings pick it up. Set `onError: "throw"` to fail the build instead.

## Output is deterministic

The same block and options always produce the same bytes: element ids are derived from a
hash of the block, not a counter or a clock. Pre-rendered SVGs diff cleanly, and a build
that did not change a diagram does not change its file.

---

### Migrate from Camunda 7

Convert Camunda 7 BPMN models to Camunda 8 with casen migrate c7 or convertCamunda7() — what is converted, what needs a person and why, how JUEL becomes FEEL, and how this relates to Camunda's own migration tools.

Source: https://bpmnkit.com/docs/guides/migrate-from-camunda-7

Camunda 7 Community Edition reached end of life with 7.24 in October 2025. Enterprise support
continues to 2030, and the community forks [Operaton](https://operaton.org) and
[CIB seven](https://www.cibseven.org) carry the Camunda 7 engine forward. If you move to
Camunda 8, your models must change: Camunda 8 reads `zeebe:` extensions and FEEL, and it
ignores `camunda:` extensions and JUEL.

BPMN Kit converts the model. It rewrites what can be rewritten mechanically, and it reports
every Camunda 7 construct it finds, with a severity and a Camunda 8 suggestion:

- **convertible** — rewritten. The Camunda 8 model does the same thing.
- **manual** — Camunda 8 has an equivalent, but a person must write or check it. Examples are a
  job worker for a Java delegate, or a correlation key for a message.
- **unsupported** — Camunda 8 has no equivalent. The model, or the system around it, must change.

## Who this is for

- Teams that have a folder of Camunda 7 `.bpmn` files and want to know how much work the
  models are, before they plan the migration.
- Teams that work in TypeScript or JavaScript and do not want a Java toolchain to convert
  models.
- CI pipelines: `casen migrate c7 --check` fails while manual work remains.

## Run it

```sh
casen migrate c7 models/*.bpmn            # writes models/*.c8.bpmn
casen migrate c7 models/*.bpmn --out c8   # writes c8/*.bpmn
casen migrate c7 models/*.bpmn --check    # report only, exit 1 on manual work
```

[`casen migrate`](/docs/cli/migrate) has the flags and the JSON format. From code:

```typescript
import { Bpmn, convertCamunda7 } from "@bpmnkit/core"

const { definitions, report } = convertCamunda7(Bpmn.parse(xml))
for (const f of report.findings) console.log(f.severity, f.elementId, f.construct, f.message)
const c8Xml = Bpmn.export(definitions)
```

`analyzeCamunda7(definitions)` returns the same report and does not change the model. The
`sourceXml` option of earlier versions is still accepted, but it has no effect. The parser now
keeps `camunda:` attributes on multi-instance loops and on event definitions, where Camunda 7
stores `camunda:collection` and the implementation of message throw events.

## What is converted

| Camunda 7 | Camunda 8 | Severity |
| --- | --- | --- |
| `camunda:type="external"` + `camunda:topic` | `zeebe:taskDefinition type` = the topic | convertible |
| `camunda:class` | `zeebe:taskDefinition type` = the class's Spring bean name (`com.acme.ShipOrderDelegate` → `shipOrderDelegate`), plus a `class` task header with the original | manual — write a job worker |
| `camunda:delegateExpression="${bean}"` | type `bean` (the element id if the expression is not a single bean), plus a `delegateExpression` header | manual |
| `camunda:expression` | type = element id, plus `expression` and `resultVariable` headers | manual |
| `camunda:field` with a string value | a task header with the same name | convertible |
| `camunda:inputOutput` | `zeebe:ioMapping`: `${…}` translated, text becomes a FEEL string, `camunda:list` / `camunda:map` become FEEL lists and contexts, an empty parameter becomes `null` | convertible, per parameter |
| `conditionExpression` `${…}` | `=…` FEEL | convertible when provable |
| `camunda:asyncBefore` / `asyncAfter` / `exclusive` / `jobPriority` | removed | convertible — see below |
| `camunda:failedJobRetryTimeCycle` `R5/PT5M` | `zeebe:taskDefinition retries="5"` | convertible; the interval is manual |
| user task | `zeebe:userTask` (a Camunda user task) | convertible |
| `camunda:assignee`, `candidateUsers`, `candidateGroups` | `zeebe:assignmentDefinition` | convertible; a candidate *expression* is manual, because Camunda 8 needs a list of strings |
| `camunda:dueDate`, `followUpDate` | `zeebe:taskSchedule` | convertible for expressions and ISO 8601 date-times with a zone |
| `camunda:priority` 0–100 | `zeebe:priorityDefinition` | convertible |
| `camunda:formRef` + `formRefBinding` | `zeebe:formDefinition formId` + `bindingType` | convertible; a `version` binding is manual |
| `camunda:formKey` | `zeebe:formDefinition externalReference` | convertible; `embedded:` and `camunda-forms:` keys are manual |
| `camunda:decisionRef` + `resultVariable` | `zeebe:calledDecision` | convertible with `mapDecisionResult="singleEntry"`; other result mappers are manual |
| `calledElement` + `camunda:calledElementBinding` | `zeebe:calledElement processId` + `bindingType` | convertible |
| `camunda:in` / `camunda:out` | `zeebe:input` / `zeebe:output`, and `propagateAllParentVariables` / `propagateAllChildVariables="false"` unless `variables="all"` | convertible |
| `camunda:in businessKey="#{execution.processBusinessKey}"` | removed: a child inherits the parent's business ID (Camunda 8.9+) | convertible |
| `camunda:collection` / `elementVariable` | `zeebe:loopCharacteristics inputCollection` / `inputElement` | convertible |
| completion condition with `nrOf…Instances` | FEEL with `numberOf…Instances` | convertible |
| timer `${…}` | `=…` FEEL | convertible when provable |
| script task, `scriptFormat="feel"` (or `juel`) | `zeebe:script expression` + `resultVariable` | convertible |
| `camunda:versionTag` | `zeebe:versionTag` | convertible |
| `camunda:properties` | `zeebe:properties` | convertible |

The file is marked `modeler:executionPlatform="Camunda Cloud"` (version `8.8.0` by default),
and the `zeebe` namespace is declared. If the converter writes a Camunda 8 equivalent, it
removes the Camunda 7 original. If it does not, it keeps the original in the file. Camunda 8
ignores `camunda:` content, so nothing is lost, and the next person can see what the model
used to do.

## What is not converted, and why

- **Java delegates, listeners and scripts.** Camunda 8 runs no user code in the engine. Every
  delegate becomes a job worker. The converter chooses the job type and keeps the original
  class or expression as a task header, so that one generic worker can dispatch on it while
  you port the code. Execution and task listeners become job-worker listeners in Camunda 8
  (`zeebe:executionListeners`, `zeebe:taskListeners`). The converter names the matching event
  type, but it does not write the listener. Groovy and JavaScript scripts must be rewritten
  as FEEL or as a worker.
- **Message correlation.** Camunda 7 correlates a message by an API call (business key,
  variables or instance id). The model does not name a key. Camunda 8 requires a
  `correlationKey` for every message catch, and only you know which variable it is.
- **Asynchronous continuations.** Camunda 8 has none. The engine commits after every step,
  and every job-based task is already a wait state, so there is no transaction boundary to
  place. A failure does not roll back to the last async boundary. A job failure retries the
  job, and an expression failure raises an incident on the element.
- **Retry intervals.** The retry count goes to the task definition. The back-off is not part
  of the Camunda 8 model: the worker gives it when it fails the job. A zero interval needs
  nothing.
- **Decision result mappers.** Camunda 8 stores the decision's own result: a value for one
  output, a context for several outputs, and a list for collect hit policies. This matches
  Camunda 7's `singleEntry`. For other mappers, check what downstream elements read.
- **No equivalent (unsupported):** `camunda:historyTimeToLive` (retention is configured for
  the cluster), `candidateStarterGroups` / `candidateStarterUsers` (use authorizations),
  `camunda:initiator`, `take` listeners on sequence flows, `timeout` task listeners, retry
  cycles on elements that have no job, standard loops, CMMN case calls, tenant ids on calls
  and decisions.
- **Anything else with the `camunda:` prefix** is reported as `manual` and kept. The report
  never omits a construct.

## JUEL to FEEL

The converter translates a JUEL expression only when the result is provably the same. This
means a single `${…}` or `#{…}` that contains only:

- variable paths (`order.customer.vip`),
- string, number, boolean and `null` literals,
- comparisons (`==`, `eq`, `!=`, `ne`, `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`),
- `&&` / `and`, `||` / `or`, `!` / `not`,
- `+`, `-`, `*`, `/`, `div`, and parentheses.

| JUEL | FEEL |
| --- | --- |
| `${approved && order.total <= 1000}` | `=approved and order.total <= 1000` |
| `${status eq 'open'}` | `=status = "open"` |
| `${!approved}` | `=not(approved)` |
| `${nrOfCompletedInstances / nrOfInstances >= 0.6}` (completion condition) | `=numberOfCompletedInstances / numberOfInstances >= 0.6` |

Everything else is kept and reported as `manual`, with the reason. This includes method calls,
`empty`, the `?:` operator, indexing (zero-based in JUEL, one-based in FEEL), `%` (FEEL's
`modulo` uses a different sign rule), the engine objects `execution`, `task` and
`authenticatedUserId`, and text mixed with `${…}`.

"Provable" assumes that the operands are not null. JUEL changes `null` to `false` in boolean
operations, but FEEL keeps it as `null`. For example, `${!approved}` is `true` in Camunda 7
when `approved` is not set. In Camunda 8, `not(approved)` is `null`, so the flow is not taken.
If a variable can be missing, give it a default before the gateway.

## Before and after

A Camunda 7 service task, as Camunda Modeler writes it:

```xml
<bpmn:serviceTask id="Task_charge" name="Charge payment" camunda:asyncBefore="true"
    camunda:type="external" camunda:topic="charge-payment">
  <bpmn:extensionElements>
    <camunda:inputOutput>
      <camunda:inputParameter name="amount">${order.total}</camunda:inputParameter>
      <camunda:inputParameter name="currency">EUR</camunda:inputParameter>
      <camunda:outputParameter name="paymentId">${transactionId}</camunda:outputParameter>
    </camunda:inputOutput>
    <camunda:failedJobRetryTimeCycle>R5/PT5M</camunda:failedJobRetryTimeCycle>
  </bpmn:extensionElements>
</bpmn:serviceTask>
```

After `casen migrate c7`:

```xml
<bpmn:serviceTask id="Task_charge" name="Charge payment">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="charge-payment" retries="5"/>
    <zeebe:ioMapping>
      <zeebe:input source="=order.total" target="amount"/>
      <zeebe:input source="=&quot;EUR&quot;" target="currency"/>
      <zeebe:output source="=transactionId" target="paymentId"/>
    </zeebe:ioMapping>
  </bpmn:extensionElements>
</bpmn:serviceTask>
```

The report for this element has four convertible findings (async, topic, mappings, retry
count). It also has one manual finding: the worker must supply the five-minute back-off when
it fails the job.

The converted output is checked against BPMN Kit's Camunda 8 deploy lint. Everything reported
as convertible lints clean. The remaining deploy errors belong to elements with a manual
finding. An example is a receive task that has no correlation key yet.

## Camunda's own tools

This converter does not replace Camunda's migration tooling. The two work well together:

- Camunda's **Migration Analyzer and Diagram Converter** do the same job as this converter, as
  a web app and a Java CLI. Use whichever fits your toolchain, or run both and compare the
  reports.
- Camunda's **code conversion** (OpenRewrite recipes) and the **Camunda 7 adapter** port the
  Java side: delegates to job workers. BPMN Kit converts only models. Its `class` /
  `delegateExpression` task headers are intended for an adapter-style worker.
- Camunda's **Data Migrator** moves running and historic process instances. BPMN Kit does not
  move data.

If you do not want to migrate yet, [Operaton](https://operaton.org) and
[CIB seven](https://www.cibseven.org) are drop-in continuations of the Camunda 7 engine. Your
models stay as they are. BPMN Kit keeps `camunda:` content on a round trip, so you can edit
those models with BPMN Kit tools in the meantime.

## Sources

The Camunda 8 semantics above come from the Camunda documentation that ships with this
repository as `@bpmnkit/camunda-docspack`:

- *Service tasks* — task definition, retries and job priority (`zeebe:jobPriorityDefinition`).
- *User tasks* — assignments (static values and expressions, list types), forms (`formId`,
  `bindingType`, `externalReference`).
- *Call activities* — binding types and business ID propagation (8.9 default, 8.10
  `businessId`). *Variables* — propagation by BPMN element, including
  `propagateAllChildVariables`.
- *Business rule tasks* — called decision and a required `resultVariable`. *Script tasks* —
  `zeebe:script`.
- *Expressions* — FEEL, the `=` prefix, expressions versus static values.
- *Message events* — a correlation key is required, except for message start events.
- *Execution listeners* and *user task listeners* — job-based listeners and their event types.
- *Process instance migration: migrating from Camunda 7* — points to the Data Migrator for
  instance data.

The pack does not contain the "Migrating from Camunda 7" guide itself. The descriptions of
Camunda's Migration Analyzer, Diagram Converter, code conversion and Camunda 7 adapter come
from Camunda's public migration documentation, not from the pack.

---

### Testing Processes

Unit-test BPMN processes in Vitest or Jest with @bpmnkit/engine/testing — job and connector mocks, manual job completion, a virtual clock for timers, BPMN matchers and path coverage. No Docker, no cluster.

Source: https://bpmnkit.com/docs/guides/testing-processes

Camunda's own process-testing library, Camunda Process Test, is written for Java, and its
JavaScript port starts a Zeebe container. `@bpmnkit/engine/testing` gives TypeScript teams
the same style of test without either. It runs your BPMN on the in-process
[simulator](/docs/guides/simulation), so a test file is ordinary Vitest or Jest and a whole
suite finishes in milliseconds.

It gives you:

- **Job mocks** by job type, with fixed results, failures, BPMN errors or a handler.
- **Manual job completion** for tasks you want to drive step by step, user tasks included.
- **Connector mocks** that map a fake response through the task's `resultVariable` and
  `resultExpression`, the same way the connector runtime does.
- **A virtual clock.** `advanceTime("P1D")` fires timers at once, with no real waiting.
- **Matchers** such as `toHaveCompleted()`, `toHavePassed([...])` and
  `toHaveVariables({...})`.
- **Path coverage** of the flow nodes and sequence flows your runs reached.
- **AI agent mocks** that script or replay which tools an agent calls. See
  [Testing AI Agents](/docs/guides/testing-ai-agents).

The simulator is not Zeebe. Before you rely on a test, read
[what the simulator does not execute](#what-the-simulator-does-not-execute).

## Install

```sh
npm install --save-dev @bpmnkit/engine vitest
```

`vitest` is an optional peer dependency. It is needed only for the
`@bpmnkit/engine/testing/vitest` entry point. Jest users do not need it.

## A complete Vitest example

```typescript
// order-process.test.ts
import { afterAll, beforeAll, expect, it } from "vitest"
import "@bpmnkit/engine/testing/vitest"
import { createProcessTest, formatCoverage } from "@bpmnkit/engine/testing"
import type { ProcessTest } from "@bpmnkit/engine/testing"

let t: ProcessTest

beforeAll(async () => {
  t = await createProcessTest({
    bpmn: new URL("./order-process.bpmn", import.meta.url),
    dmn: new URL("./discount.dmn", import.meta.url), // optional
  })
})

afterAll(() => {
  console.log(formatCoverage(t.coverage()))
  t.dispose()
})

it("ships a paid order", async () => {
  t.mockJob("payment", { result: { paid: true } })

  const run = await t.start("order-process", { amount: 10 })
  expect(run).toBeWaitingAt("ship") // "ship" has no mock, so its job waits

  await run.completeJob("ship", { trackingId: "1Z999" })

  expect(run).toHaveCompleted()
  expect(run).toHavePassedInOrder(["payment", "ship"])
  expect(run).toHaveVariables({ paid: true, trackingId: expect.any(String) })
})

it("cancels an unpaid order", async () => {
  t.mockJob("payment", { result: { paid: false } })

  const run = await t.start("order-process", { amount: 10 })

  expect(run).toHaveCompleted()
  expect(run).toHaveNotPassed(["ship"])
})
```

`createProcessTest` accepts parsed definitions, XML text, a file path or a `file:` URL for
`bpmn`, `dmn` and `forms`. Each can also be an array. A relative path resolves against the
working directory, so `new URL("./x.bpmn", import.meta.url)` is the reliable choice.

`start()` and every action on a run (`completeJob`, `publishMessage`, `advanceTime` and the
others) return after the process has run as far as it can without more input. You never
need to add a wait or a poll.

### Vitest setup

Import `@bpmnkit/engine/testing/vitest` once. This registers the matchers and adds their
types to Vitest's `Assertion`. To register them for every file, use a setup file:

```typescript
// vitest.config.ts
import { defineConfig } from "vitest/config"

export default defineConfig({
  test: { setupFiles: ["@bpmnkit/engine/testing/vitest"] },
})
```

If you use a setup file, add `import "@bpmnkit/engine/testing/vitest"` to a `.d.ts` file
in your project too, so that TypeScript sees the matcher types.

### Jest setup

The matchers are plain `expect.extend` matchers. Register them in a setup file and add
their types to Jest's `Matchers`:

```typescript
// jest.setup.ts  (add to "setupFilesAfterEnv" in jest.config)
import { expect } from "@jest/globals"
import { bpmnMatchers } from "@bpmnkit/engine/testing"
import type { BpmnMatchers } from "@bpmnkit/engine/testing"

expect.extend(bpmnMatchers)

declare module "expect" {
  interface Matchers<R> extends BpmnMatchers<R> {}
}
```

If you use `@types/jest` globals, declare the types with
`declare global { namespace jest { interface Matchers<R> extends BpmnMatchers<R> {} } }`.
The package ships ES modules, so run Jest in its ESM mode or through a transformer that
handles ESM.

## Jobs

Each job type in the deployed BPMN gets a worker. What the worker does depends on whether
the type has a mock:

- **Mocked**: the mock handles the job.
- **Not mocked**: the job waits. You complete it with `run.completeJob(...)`, as Zeebe
  would wait for a worker.

```typescript
t.mockJob("payment", { result: { paid: true } })                   // complete with variables
t.mockJob("payment", { fail: "card declined" })                    // fail the job
t.mockJob("payment", { throwError: { code: "DECLINED" } })         // throw a BPMN error
t.mockJob("payment", (job) => ({ paid: job.variables.amount < 100 })) // compute; throw to fail

const payment = t.mockJob("payment", { result: { paid: true } })
payment.calls           // every job the mock handled: elementId, variables, headers, ...
payment.restore()       // later jobs of this type wait for completeJob again
```

To drive a waiting job, name its element id or its job type:

```typescript
run.jobs                                   // [{ elementId: "ship", type: "ship", ... }]
await run.completeJob("ship", { trackingId: "1Z999" })
await run.failJob("ship", "carrier down")
await run.throwError("ship", "NO_STOCK", "Out of stock")
```

A Camunda user task (`zeebe:userTask`, no job type) is a job of type `userTask`. Complete
it by its element id: `await run.completeJob("review", { approved: true })`. If no job is
waiting at the id, the error lists the jobs and elements that are waiting.

## Connectors

An outbound connector is a job whose type is the connector's id. Use `mockConnector` with
the response the connector would return. The element's `resultVariable` and
`resultExpression` headers map that response into variables:

```typescript
t.mockConnector("io.camunda:http-json:1", {
  response: { status: 200, body: { main: { temp: 21.5 } } },
})
// resultVariable "weather"          → weather = the whole response
// resultExpression "={temp: body.main.temp}" → temp = 21.5
```

The response's fields are in scope in `resultExpression`, and `response` is too. The
expression must produce a context. A `null` result maps nothing. A handler
`(job) => response` and the `{ fail }` and `{ throwError }` forms also work.
`mapConnectorResponse(response, headers)` is exported if you want the mapping on its own.
`errorExpression` is not evaluated.

## Dry run

`dryRun(definitions)` runs a process once from start to end with every outside call
mocked. It needs no test file and no mocks. It proves that a diagram, such as one an AI
generated, is executable and not only well-formed:

```typescript
import { dryRun } from "@bpmnkit/engine/testing"

const result = await dryRun(definitions)
result.reachedEnd   // true when every token finished
result.path         // elements entered, in order
result.connectors   // connector tasks passed, each mocked
result.stoppedAt    // where it stopped, when it did not reach the end
result.error        // why: the incident, or what it still waited for
```

- **Connectors.** Each connector answers an empty HTTP 200, `{ status: 200, headers: {}, body: {} }`,
  mapped by its result headers. Pass `response` for another answer.
- **Other jobs.** Service tasks, user tasks and agents complete with no variables.
- **Gateways.** A gateway takes the branch its conditions pick, which is the default flow
  when none holds. Pass `variables` to start with others.
- **Multi-instance.** A multi-instance over a variable (`=recipients`) runs over a one-item
  list, unless `variables` gives the list.
- **Waits.** When the run waits, the message it waits for is delivered. Otherwise the clock
  moves on a day, which fires due timers. `steps` lists what was done.

A process that cannot finish does not throw: `reachedEnd` is false, and `stoppedAt` and
`error` say where and why. For example, a gateway with no matching condition and no default
flow. `casen synth --check` and Drop's generator run it on what they produce.

## AI agents

An [AI Agent sub-process](/docs/guides/ai-agents) runs as a job of type
`io.camunda.agenticai:aiagent-job-worker:1`. `mockAiAgent` scripts the model's turns: which
tools it calls, with which arguments, and its final answer. The tools inside the ad-hoc
sub-process then run like any other task:

```typescript
const agent = t.mockAiAgent("support-agent", [
  { toolCalls: [{ name: "lookup-order", arguments: { orderId: "1042" } }] },
  { responseJson: { answer: "It ships tomorrow.", resolved: true } },
])
const run = await t.start("support", { customerMessage: "Where is order 1042?" })
expect(agent).toHaveCalledTools([{ name: "lookup-order", arguments: { orderId: "1042" } }])
```

A script can also be a recorded cassette file, and coverage counts the tools that ran. See
[Testing AI Agents](/docs/guides/testing-ai-agents). To mock the agent as a black box, use
`mockJob` with the output you want: `{ result: { agent: { responseText: "Refund approved" } } }`.

## Messages

```typescript
const run = await t.start("order-process")
await run.publishMessage("payment-confirmed") // the bpmn:message name, or its id
```

A message goes to the run you publish it on. If nothing in that run waits for the message,
`publishMessage` throws. **Gaps:** a message cannot carry variables, and correlation keys
are not evaluated. To set the variables a message would carry, complete an earlier job
with them.

## The virtual clock

A `ProcessTest` puts engine timers on a virtual clock. A timer fires only when you advance
the clock:

```typescript
const t = await createProcessTest({ bpmn, startTime: "2026-06-01T00:00:00Z" })
const run = await t.start("reminder-process")
expect(run).toBeWaitingAt("wait_one_day")

await t.advanceTime("PT23H")   // ISO 8601 duration, or milliseconds
expect(run).toBeWaitingAt("wait_one_day")

await t.advanceTime("PT1H")
expect(run).toHaveCompleted()
t.now()                        // 2026-06-02T00:00:00.000Z
```

`advanceTime` fires the timers that fall due in order. After each timer, the processes run
before the next timer fires. Thus a boundary timer that interrupts a task has an effect
before a later timer fires. `run.advanceTime(...)` is the same call. `startTime` sets where
the clock starts. The default is the real time when the test is created. Set it when a
timer uses an absolute `timeDate`.

The test helpers do not use fake timers, so `vi.useFakeTimers()` is not necessary. It also
does not block them if your own code uses it. Call `dispose()` in `afterAll`: it returns
engine timers to the real clock and cancels the runs that are still active.

## Coverage

`t.coverage()` counts the flow nodes that the file's runs entered and the sequence flows
they took:

```typescript
const report = t.coverage()
report.elements        // { total: 14, covered: 12, percent: 85.7, uncovered: ["end_cancel", ...] }
report.flows           // the same, for sequence flows
report.tools           // the same, for the tools of AI agents
report.processes       // one entry per deployed process

console.log(formatCoverage(report))
// BPMN coverage
//   order-process  elements 12/14 (85.7%)  flows 13/15 (86.7%)
//     elements not reached: end_cancel, notify_customer
//     flows not taken: Flow_unpaid, Flow_notify
```

The simulator's events name elements but not flows. For this reason, the taken flows are
inferred: a parallel join counts all its incoming flows, and any other element counts the
incoming flow from the source that completed most recently. For sequential paths the result
is exact. Elements inside sub-processes are counted, and data objects are not.

## Matchers

| Matcher | Passes when |
|---|---|
| `toHaveCompleted()` | The instance ended normally |
| `toHaveFailed(error?)` | The instance failed. `error` is a substring or a `RegExp` |
| `toBeWaitingAt(ids)` | Each listed element holds a token now |
| `toHavePassed(ids)` | Each listed element completed at least once, in any order |
| `toHavePassedInOrder(ids)` | The elements completed in this order. Other elements can come between them |
| `toHaveNotPassed(ids)` | None of the listed elements completed |
| `toHaveVariables(vars)` | Each listed variable is equal. Asymmetric matchers such as `expect.any(Number)` work |
| `toHaveCalledTools(calls)` | On a `mockAiAgent` handle: the agent called exactly these tools, in this order. See [Testing AI Agents](/docs/guides/testing-ai-agents) |

Every matcher works with `.not`. When a matcher fails, the message gives the run's state,
its error, the elements that wait and the elements that completed.

## What the simulator does not execute

The tests are only as good as the simulator's coverage of your model. Read
[Conformance](/docs/getting-started/conformance) for the element-by-element list. The gaps
most likely to affect a test are:

- Some elements complete without their semantics, or are not modelled. See the conformance
  table for which elements are affected.
- A BPMN error thrown from a job (`{ throwError }` or `run.throwError`) fails the instance.
  An error boundary event on the task does not catch it.
- A variable that is first written inside an embedded sub-process stays local to that
  sub-process and is lost when it completes. Zeebe propagates it to the process. To keep
  such a variable, pass it as a start variable.
- Message variables and correlation keys (see [Messages](#messages)).
- Inner activities of an ad-hoc sub-process without a task definition. An AI agent's tools
  do run (see [AI agents](#ai-agents)).

Engine timers are module-level, so the `ProcessTest` created last drives them until it is
disposed. Use one `ProcessTest` for each test file. This is the `beforeAll` pattern above.
Vitest runs each file in isolation.

### Zeebe semantics (future)

`@bpmnkit/engine/wasm-runner` runs `.bpmn.tests.json` scenarios on Reebe, which has more
of Zeebe's semantics. A `mode: "wasm"` option for `createProcessTest` is planned but not
yet available. The runner drives a scenario from start to end in one call; `casen test`
uses it, and every scenario in the [template gallery](/templates) passes on it.

## See also

- [Simulation](/docs/guides/simulation): the `Engine` API under these helpers.
- `casen test`: runs the `.bpmn.tests.json` scenario sidecars that `casen synth` writes,
  without a test runner.

---

### Typed Workers

Generate TypeScript types from BPMN so that job types, variables, headers, message names and error codes are checked at compile time, and check that every job type has a worker.

Source: https://bpmnkit.com/docs/guides/typed-workers

A job worker depends on names that the BPMN model defines: the job type, the variables it reads, the
variables it returns, and the error codes it throws. If you type these names by hand, a typo shows
only at runtime, as a job that no worker takes or as an incident.

`casen gen types` reads the BPMN and generates the TypeScript types for these names. The compiler
then checks them for you.

## Generate the types

```sh
casen gen types processes/ --out src/generated/bpmn-types.ts
```

The command accepts files, directories and globs. Commit the generated file, and add the `--check`
command to CI so that the file stays current:

```sh
casen gen types processes/ --out src/generated/bpmn-types.ts --check   # exits 1 when stale
```

For a service task like this one:

```xml
<bpmn:serviceTask id="Charge" name="Charge card">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="charge-card" />
    <zeebe:ioMapping>
      <zeebe:input source="=order.total" target="amount" />
      <zeebe:output source="=transactionId" target="txId" />
    </zeebe:ioMapping>
    <zeebe:taskHeaders>
      <zeebe:header key="provider" value="stripe" />
    </zeebe:taskHeaders>
  </bpmn:extensionElements>
</bpmn:serviceTask>
<bpmn:boundaryEvent id="Declined" attachedToRef="Charge">
  <bpmn:errorEventDefinition errorRef="Err_Declined" />  <!-- errorCode="PAYMENT_DECLINED" -->
</bpmn:boundaryEvent>
```

the command generates:

```ts
export interface ChargeCardVariables {
	amount: unknown
}
export interface ChargeCardOutput {
	transactionId: unknown
}
export interface ChargeCardHeaders {
	readonly provider: "stripe"
}
export type JobTypes = {
	"charge-card": {
		variables: ChargeCardVariables
		output: ChargeCardOutput
		headers: ChargeCardHeaders
		errors: "PAYMENT_DECLINED"
		processIds: "order-process"
		elementIds: "Charge"
	}
}
```

The file also exports `ProcessId`, `JobType`, `MessageName` (the `Messages` interface documents the
correlation key of each message), `SignalName`, `ErrorCode` and `EscalationCode`. Each of these has a
`const` array, for example `jobTypes` and `errorCodes`, that you can use at runtime.

## Use the types with `@bpmnkit/worker-client`

Give the `JobTypes` map to `createWorkerClient`. The client then types each job by its job type:

```ts
import { createWorkerClient } from "@bpmnkit/worker-client"
import type { JobTypes } from "./generated/bpmn-types.js"

const client = createWorkerClient<JobTypes>()

for await (const job of client.poll("charge-card")) {   // a misspelt job type is a compile error
	const amount = job.variables.amount                  // "amont" is a compile error
	if (job.customHeaders.provider === "stripe") {
		// …
	}
	if (declined) {
		await job.throwError("PAYMENT_DECLINED", "Card declined")   // only codes that a catch event handles
	} else {
		await job.complete({ transactionId })                // required output keys are enforced
	}
}
```

If you do not give a type argument, the client stays untyped, as before.

## Use the types with another client

The types are plain TypeScript, so you can use them with any client. With
`@camunda8/orchestration-cluster-api`, give the handler's variables and result the types from the
`JobTypes` map:

```ts
import type { JobTypes } from "./generated/bpmn-types.js"

type Charge = JobTypes["charge-card"]
const jobType: keyof JobTypes = "charge-card"

camunda.createJobWorker({
	jobType,
	jobHandler: async (job) => {
		const variables = job.variables as Charge["variables"]
		const output: Charge["output"] = { transactionId: await charge(variables.amount) }
		return job.complete(output)
	},
	// …
})
```

## Check workers against the BPMN

```sh
casen gen types processes/ --check-workers "src/**/*.ts" --strict
```

The check scans your sources for worker registrations. It then reports two types of mismatch:

- A BPMN job type that has no worker.
- A worker whose job type no BPMN element uses. Usually this is a typo or a job type that was renamed.

`--strict` makes the command exit 1 when there is a mismatch. The scan is a heuristic: it finds
only job types that are string literals in the common registration forms. The
[`casen generate` reference](/docs/cli/generate#check-workers-against-the-bpmn) lists these forms.
Job types that start with `io.camunda` are Camunda connectors. The connector runtime runs them, so
the check never reports them as missing.

## How the types are derived

FEEL cannot be typed statically, so every value is `unknown`. But the keys are exact, and a key is
optional when the model does not guarantee it.

| What | Rule |
|---|---|
| Job types | Every element with a static `zeebe:taskDefinition` type: service, send, script and business rule tasks, message throw events, and ad-hoc sub-processes (AI Agent job workers). User tasks are excluded. A job type written as a FEEL expression (`=…`) is skipped and listed in the file header. |
| Variables | The targets of the element's `zeebe:input` mappings, all required. If the element has no input mappings, the variables in scope on its incoming flows, from the variable-flow analysis, all optional. |
| Output | The variables that the element's `zeebe:output` sources read, less the element's own input targets. A key is required when the source is a plain reference such as `=total`, and optional otherwise. If the element has no output mappings, the output is the variables that downstream elements read and that nothing else in the process sets, all optional. |
| Headers | The `zeebe:taskHeaders` of the element, with their values as literal types. |
| Errors | The error codes that error boundary events catch on the element and on its enclosing sub-processes, and the codes that error event sub-processes catch in those scopes. A catch-all error event makes the type `string`. If nothing catches an error, the type is `never`, because an uncaught error raises an incident. |
| Shared job types | When two or more elements use the same job type, their contracts are merged. A key is required only when all of the elements require it. |
| Processes | Only executable processes (`isExecutable="true"`) are read. |

The output is deterministic: everything is sorted. Two job types that give the same TypeScript name,
for example `ship-order` and `ship_order`, get a numeric suffix (`ShipOrder`, `ShipOrder2`).

To generate the types from code, use the same function that the CLI uses:

```ts
import { Bpmn, generateProcessTypes, extractProcessContract } from "@bpmnkit/core"

const source = generateProcessTypes([Bpmn.parse(orderXml), Bpmn.parse(returnsXml)])
const contract = extractProcessContract(Bpmn.parse(orderXml))   // the same data as objects
```

---

### Testing AI Agents

Put an AI Agent Sub-process under deterministic tests — script or replay the tools the model calls, check the arguments it passes and the path the process takes, and measure which tools your tests exercise. No LLM, no network.

Source: https://bpmnkit.com/docs/guides/testing-ai-agents

An [AI Agent Sub-process](/docs/guides/ai-agents) lets a model choose which tools to call.
That choice changes from run to run, so a process with an agent is hard to test. Camunda
reports that only 11% of agentic projects reach production. `@bpmnkit/engine/testing`
makes the agent step deterministic: you write down, or record once, what the model decides.
The test then runs the real tools of the ad-hoc sub-process, the real `fromAi()` mappings and
the real process around them.

This guide extends [Testing Processes](/docs/guides/testing-processes). Read that first for
`createProcessTest`, job mocks and the matchers.

## How the mock plays the connector

The simulator runs an ad-hoc sub-process that has a job worker in the same way as Zeebe:

1. The agent's job sees `adHocSubProcessElements`: the tools, with their documentation and
   `fromAi()` parameters, in Zeebe's shape. A parameter is named by the whole reference that
   `fromAi()` tags, so `fromAi(toolCall.orderId, "The order number")` gives
   `{ name: "toolCall.orderId", description: "The order number" }`. A field that is empty
   is left out, as Zeebe does: an element without `zeebe:properties` has no `properties`.
2. `mockAiAgent` takes the next **turn** of your script. A turn with `toolCalls` completes the
   job with an `adHocSubProcess` job result that activates those tools. Each tool gets a
   `toolCall` variable: `{ ...arguments, _meta: { id, name } }`. Its `fromAi(toolCall.x)`
   input mappings read the variable.

**Argument names.** Write `arguments` as the model sends them: `{ orderId: "1042" }`, not
`{ "toolCall.orderId": "1042" }`. The AI Agent connector offers the model each
`toolCall.<name>` parameter as `<name>`, and puts the model's arguments in the `toolCall`
variable, where `fromAi(toolCall.orderId)` reads them. A tool parameter outside the
`toolCall.` namespace, such as `fromAi(orderId)`, or a nested one, such as
`fromAi(toolCall.order.id)`, cannot be offered to the model. The connector fails for it, and
so does the mock when the tool is called.
3. The tools run as normal tasks, with mocks or with `run.completeJob`. When a tool ends,
   `outputElement` appends `{ id, name, content: toolCallResult }` to `toolCallResults`, and
   the agent gets a new job.
4. When every tool of the turn has a result, the mock takes the next turn. A turn with
   `responseText` or `responseJson` ends the agent. The mock sets
   `agent = { responseText, responseJson, context }`, and the output mapping of the ad-hoc
   sub-process takes the value from there.

## A worked example

The `ai-agent-tool-loop` template (`casen template use ai-agent-tool-loop`) is a support agent
with three tools: `search-kb`, `lookup-order` and `create-ticket`. After the agent, a gateway
reads `agent.responseJson.resolved`.

```typescript
// support.test.ts
import { afterEach, beforeEach, expect, it } from "vitest"
import "@bpmnkit/engine/testing/vitest"
import { createProcessTest } from "@bpmnkit/engine/testing"
import type { ProcessTest } from "@bpmnkit/engine/testing"

let t: ProcessTest

beforeEach(async () => {
  t = await createProcessTest({ bpmn: new URL("./ai-agent-tool-loop.bpmn", import.meta.url) })
  t.mockJob("order-lookup", (job) => ({
    order: { id: job.variables.orderId, status: "delivered", damaged: true },
  }))
  t.mockJob("kb-search", { result: { articles: ["Returns and damaged items"] } })
  t.mockJob("ticket-create", { result: { ticketId: "T-77" } })
  t.mockJob("email-send", { result: {} })
})

afterEach(() => t.dispose())

it("opens a ticket for a damaged order and answers the customer", async () => {
  const agent = t.mockAiAgent("support-agent", [
    {
      toolCalls: [
        { name: "lookup-order", arguments: { orderId: "1042" } },
        { name: "search-kb", arguments: { query: "damaged item return" } },
      ],
    },
    { toolCalls: [{ name: "create-ticket", arguments: { summary: "Order 1042 arrived damaged" } }] },
    { responseJson: { answer: "Ticket T-77 is open.", resolved: true } },
  ])

  const run = await t.start("ai-agent-tool-loop", { customerMessage: "My order 1042 arrived broken." })

  expect(run).toHaveCompleted()
  expect(run).toHavePassedInOrder(["support-agent", "send-answer", "answered"])
  expect(agent).toHaveCalledTools([
    { name: "lookup-order", arguments: { orderId: "1042" } },
    { name: "search-kb", arguments: { query: expect.stringContaining("damaged") } },
    "create-ticket",
  ])
  // What the model saw on its second call:
  expect(agent.requests[1].toolCallResults).toEqual([
    { id: "call_1_1", name: "lookup-order", content: { id: "1042", status: "delivered", damaged: true } },
    { id: "call_1_2", name: "search-kb", content: ["Returns and damaged items"] },
  ])
})
```

`toHaveCalledTools` compares the whole sequence. Give a tool id, or `{ name, arguments }`
when the arguments matter. Asymmetric matchers work in `arguments`. Tool elements are
ordinary elements, so `toHavePassed(["create-ticket"])` and the other run matchers also work.

### The handle

| Member | What it holds |
|---|---|
| `toolCalls` | Every tool call the agent issued: `{ modelCall, id, name, arguments }` |
| `requests` | Every model call: `{ modelCall, toolCallResults, tools, variables }` |
| `remainingTurns` | Script turns that were not played |
| `cassette()` | The turns played so far, as a cassette |
| `restore()` | Removes the mock |

Turns are used in order across every run of the element. Thus a process that enters the agent
twice, or two runs in one test, read one script from start to end. A call without an `id`
gets `call_<modelCall>_<n>`.

## When the test must fail

The mock fails the run, and does not guess, when the script and the model disagree. The
message goes to `run.error`, and `toHaveCompleted()` prints it:

- **Unknown tool.** `unknown tool "issue-refund". Tools of "support-agent": search-kb,
  lookup-order, create-ticket`. This happens when a tool was renamed or removed after a
  transcript was recorded.
- **Wrong arguments.** An argument that no `fromAi()` parameter declares, or a missing required
  parameter (`fromAi` without `{ required: false }`). Arguments are named without
  `toolCall.`, as described above.
- **A tool the connector cannot offer.** A `fromAi()` parameter that is not a
  `toolCall.<name>` reference fails the call with the connector's message, for example
  `Parameter name 'summary' is not part of expected namespace 'toolCall.'.`
- **Script too short.** `the script has no turn 3 — it has 2, all played. The agent asked the
  model again with results from lookup-order`. The process needed a model call that the
  script does not have.
- **Model-call limit.** More model calls than the connector's `data.limits.maxModelCalls`.

A tool without a mock waits, as in any other test. Complete it with
`run.completeJob("create-ticket", { ticketId: "T-9" })`. The agent then continues.

## Record and replay

A **cassette** is a JSON file that holds the model's turns for one agent:

```json
{
  "version": 1,
  "agent": "support-agent",
  "turns": [
    { "toolCalls": [{ "id": "toolu_01", "name": "lookup-order", "arguments": { "orderId": "1042" } }] },
    { "responseText": "It ships tomorrow.", "responseJson": { "answer": "It ships tomorrow.", "resolved": true } }
  ]
}
```

The TypeScript type is `AgentCassette`. `parseAgentCassette(value)` validates JSON text or
parsed JSON. On an error, it gives the path of the problem, for example
`turns[0] has unknown field "tool_calls"`. `readAgentCassette(path)` and
`writeAgentCassette(path, cassette)` read and write files, and both validate. A cassette with
an `agent` field refuses to replay for another element.

**To record**, give `mockAiAgent` a handler instead of a script. The handler is your own code:
an adapter that sends `request.tools` and `request.toolCallResults` to your model, or a
transcript that you captured from a Camunda run. The testing helpers never call a model or
the network. After the run, save the turns that the handler returned:

```typescript
import { readAgentCassette, writeAgentCassette } from "@bpmnkit/engine/testing"

const CASSETTE = new URL("./damaged-order.cassette.json", import.meta.url)

it("handles a damaged order", async () => {
  const agent = process.env.RECORD
    ? t.mockAiAgent("support-agent", (request) => myModelAdapter(request)) // your code
    : t.mockAiAgent("support-agent", await readAgentCassette(CASSETTE))

  const run = await t.start("ai-agent-tool-loop", { customerMessage: "My order 1042 arrived broken." })
  if (process.env.RECORD) await writeAgentCassette(CASSETTE, agent.cassette())

  expect(run).toHaveCompleted()
})
```

**To replay**, pass the cassette. Replay is deterministic: each model call takes the next
turn, and the tools get the same arguments. If the process changes so that it needs a turn
that the cassette does not have, the run fails and tells you to re-record.

## Tool coverage

The tools are elements, so `coverage().elements` counts them. `coverage().tools` counts only
the tools, which are the elements that an AI agent can activate:

```typescript
t.coverage().tools   // { total: 3, covered: 2, percent: 66.7, uncovered: ["create-ticket"] }

console.log(formatCoverage(t.coverage()))
// BPMN coverage
//   ai-agent-tool-loop  elements 7/13 (53.8%)  flows 4/8 (50.0%)  tools 2/3 (66.7%)
//     elements not reached: create-ticket, agent-failed, queue-for-human, ...
//     flows not taken: ...
//     tools never called: create-ticket
```

A tool that no test calls is a path that no test covers.

## Limits

- The mock plays the AI Agent **Sub-process** connector
  (`io.camunda.agenticai:aiagent-job-worker:1`, which `buildAiAgentSubProcess` builds).
  For the AI Agent **Task** with a separate ad-hoc sub-process, the simulator does not
  evaluate `activeElementsCollection`. Mock that task with `mockJob`.
- The connector's `errorExpression` is not evaluated. Thus a failed tool or a model-call limit
  fails the run instead of throwing `AGENT_FAILED`.
- Two runs of the same agent element at the same time in one run, for example inside a
  parallel multi-instance, share the turn state.
- `agent.context` holds only `state` and `metrics.modelCalls`, not the conversation.

---

### Process documentation

Turn a BPMN diagram into a document to circulate — the diagram, every step in flow order with its performer and settings, and the linked DMN tables and forms — as print-ready HTML (PDF), Markdown or Word.

Source: https://bpmnkit.com/docs/guides/process-documentation

A process model answers "what happens next?" for the people who drew it. Everyone else — the
auditor, the team lead signing it off, the new colleague — wants a document: the diagram, then
each step spelled out. Camunda Modeler and Signavio users know this as a *process report*.
BPMNKit builds one from the model itself, so it never drifts from what is deployed.

## What the document contains

1. **Title and summary** — the pool or process name, and the process documentation text.
2. **Table of contents**, linking every section.
3. **The diagram**, as vector graphics, on a landscape page when printed.
4. **One section per process or pool**:
   - **Lanes and performers** — each lane and the steps it owns.
   - **Steps at a glance** — a numbered table: name, type, lane.
   - **Step details** — for every element, in *flow order* (start events first, then the order a
     token travels; each branch stays together up to its join, loops are not followed twice,
     boundary events follow their host's normal path, sub-process steps are numbered `3.1`,
     `3.2`…):
     type (e.g. *Timer boundary event (non-interrupting)*), documentation text, lane, job type
     and retries, task headers, input/output mappings, called decision and result variable,
     called process, form, assignee and candidate groups, due dates, priority, script,
     multi-instance settings, timers (`PT48H (48 hours)`), messages and correlation keys,
     errors and escalations, and the next steps — with the condition on each outgoing flow and
     the default flow marked.
5. **Message flows** between pools.
6. **Decisions** — each DMN decision table passed in: hit policy, a *When … / Then …* rule
   table, and which steps call it.
7. **Forms** — each form passed in: fields, the variable each binds, type, whether it is
   required and its options, and which user tasks show it.

The same model always produces the same bytes: nothing time-dependent is added unless you pass
a `subtitle`. All model text is escaped, so a name like `<script>` prints as text.

## From the editor

Open the **⋯ More actions** menu and pick **Export documentation…**:

| Choice | What you get |
|---|---|
| **Open print view** | The HTML document in a new tab. Use the browser's *Print → Save as PDF* — page breaks, A4 or Letter, no editor chrome. |
| **Download HTML** | The same document as one self-contained `.html` file: no scripts, no network requests. |
| **Download Markdown** | For wikis and Confluence imports. GitHub-flavoured tables, no diagram. |
| **Download Word** | A `.docx` with Word heading styles (the navigation pane and an inserted table of contents pick them up) and the diagram on a landscape page. |

In the hosted editor, the DMN and form tabs open next to the diagram are documented with it.
When embedding the editor, pass them through `initEditorHud`:

```ts
initEditorHud(editor, {
  getDocumentationContext: () => ({ decisions: [riskDmn], forms: [reviewForm] }),
})
```

## From Drop

A shared drop has a **Docs** button in its toolbar. It offers the same four choices and needs no
edit rights: anyone who can read a drop can take its documentation away. The drop's BPMN file
(the open tab, or the first BPMN file) is documented together with every DMN and form file in
the drop.

## From the CLI

```sh
casen doc export order.bpmn                                  # order.html, print-ready
casen doc export order.bpmn credit.dmn review.form --format docx
casen doc export order.bpmn --format md --out docs/order.md
```

| Flag | Meaning |
|---|---|
| `--format` | `html` (default), `md` or `docx` |
| `--out` | Output path. Default: the input name with the format's extension |
| `--title` | Document title. Default: the pool or process name |
| `--paper` | `a4` (default) or `letter`, for `docx` |

Any `.dmn` and `.form` files after the BPMN file are documented with it. There is no `--format
pdf`: print the HTML to PDF with a browser, or headless — `chrome --headless
--print-to-pdf=order.pdf order.html`.

## From code

```ts
import { Bpmn, renderDocumentationHtml, renderDocumentationMarkdown, renderDocumentationDocx } from "@bpmnkit/core"

const defs = Bpmn.parse(xml)
const html = renderDocumentationHtml(defs, { decisions: [dmn], forms: [form] })
const md = renderDocumentationMarkdown(defs)
const docx: Uint8Array = renderDocumentationDocx(defs, { paper: "letter" })
```

`buildProcessDocumentation(defs, options)` returns the structured content — processes, lanes,
elements in flow order with their properties, message flows, decisions, forms — for a renderer
of your own. `documentationToHtml`, `documentationToMarkdown` and `documentationToDocx` render
it.

## Limits

- **PDF** comes from the browser's print dialog, not from a PDF library. Chromium honours the
  landscape diagram page; other browsers print it on the page size you choose.
- **Markdown** carries no diagram. Export one with `exportSvg` and link it if the wiki allows.
- **Word** embeds the diagram as SVG, without a bitmap fallback. LibreOffice renders it, as
  do Word versions with SVG support (Microsoft 365, Word 2019 and later); older Word versions
  show no image. The Word file has no generated table of contents — insert one from
  *References → Table of Contents*.
- Only the **first diagram** is drawn. Collapsed sub-processes with their own diagram page are
  documented step by step but not drawn separately.
- DMN **decision tables** are documented; literal-expression decisions and the DRD are not.
- The document is in English. The editor's menu entries are translatable; the document's
  headings are not yet.

---

### Durable Agent Flows

Write a workflow in TypeScript, let coding agents do the steps, and let the engine remember the run across crashes and reboots.

Source: https://bpmnkit.com/docs/guides/durable-agent-flows

When a lead agent keeps its plan in its own context — what is done, what is blocked, what is
next — that plan lives in the most volatile place you have. One compaction and it is gone; one
reboot and the run dies with it, and the tokens are spent again.

A process engine is the durable place for that state. This guide puts the two together:

- **[`@bpmnkit/flow`](/docs/packages/flow)** — you write the workflow as TypeScript steps, and
  it derives the BPMN, the job types and the worker.
- **`casen agent`** — you hire coding-agent CLIs (Claude Code, Copilot, …) as job workers, and
  run them as a workforce.
- **A Camunda 8 engine** — local [Reebe](/docs/cli/casen#local-engine-reebe) or a real cluster —
  holds the run. A crash of any worker costs a job lock, not the run.

## 1. Write the flow

```typescript
// flows/pr-review.ts
import { writeFileSync } from "node:fs"
import { defineFlow } from "@bpmnkit/flow"

export const review = defineFlow("pr-review", { name: "PR review" })
  .input<{ prKey: string; repo: string }>()
  .run("fetch-diff", async ({ repo, prKey }) => ({ diff: await gh.diff(repo, prKey) }))
  .loop(
    "review-loop",
    (b) => b.agent("review", {
      role: "pr-review",
      prompt: "Review {{repo}} PR {{prKey}}. Start with APPROVE or REJECT, then the problems.\n\n{{diff}}",
      result: "verdict",
    }),
    {
      until: 'starts with(verdict, "APPROVE")',
      max: 3,
      between: (b) => b
        .agent("fix", {
          role: "feature",
          prompt: "In {{repo}}, push fixes to PR {{prKey}} for this review:\n\n{{verdict}}",
        })
        .run("refresh-diff", async ({ repo, prKey }) => ({ diff: await gh.diff(repo, prKey) })),
      escalate: { candidateGroups: "maintainers" },
    },
  )
  .approve("approve-merge", { name: "Approve merge", candidateGroups: "maintainers" })
  .run("merge", async ({ repo, prKey }) => ({ merged: await gh.merge(repo, prKey) }))
  .build()

writeFileSync("pr-review.bpmn", review.toXml())
```

Each step's output joins the variables of the steps after it, so `{{diff}}` in the prompt and
`prKey` in `merge` are checked at compile time. The `.agent()` steps do not run in your code:
they become service tasks with job types `agent:pr-review` and `agent:feature`, which the
workforce serves.

The [loop](/docs/packages/flow#loops) reviews, and while the reviewer's answer does not start
with APPROVE, fixes and reviews again. After three rounds without approval it stops spending tokens and
gives the maintainers a user task instead. The round count lives in the engine like everything
else, so a crash in round 2 resumes in round 2.

## 2. Start an engine and deploy

```sh
casen reebe start --port 26500 --grpc-port 26501   # local engine, SQLite-backed
casen profile create local --base-url http://localhost:26500/v2 --auth-type none
casen profile use local
casen deploy deploy pr-review.bpmn
```

REST goes on 26500 because that is where `casen deploy` and the flow worker look by default
(`ZEEBE_ADDRESS`); Reebe's gRPC gateway, which also defaults to 26500, moves to 26501. Any
Camunda 8 cluster works the same way — point the profile and `ZEEBE_ADDRESS` at it instead.

## 3. Hire the workforce

A hire saves a profile: the CLI to run, the roles it takes on, and how many jobs it works on at
once. Everything after `--` is the command.

```sh
casen agent hire claude --roles pr-review,plan --rank senior -- claude -p
casen agent hire copilot --roles feature --instances 3 -- copilot -p "{prompt}"
casen agent list
```

The prompt goes to the CLI on stdin, unless an argument contains `{prompt}` — then it goes
there. Profiles are saved in `workforce.json`, next to casen's profile config.

| Flag | Default | Description |
|---|---|---|
| `--roles` | — (required) | Comma-separated roles the agent takes on |
| `--rank` | — | Also serve steps that ask for this rank |
| `--instances` | `1` | How many jobs the agent works on at once |
| `--timeout` | `30` | Minutes one run may take before it is stopped and the job failed |
| `--cwd` | current directory | Directory the CLI runs in |

`casen agent hire` with an existing name updates that agent; `casen agent fire <name>` removes
it.

### Roles and ranks

An `.agent()` step names a role and, optionally, a rank:

| Step | Job type | Served by |
|---|---|---|
| `{ role: "pr-review" }` | `agent:pr-review` | any agent with the `pr-review` role |
| `{ role: "pr-review", rank: "senior" }` | `agent:senior:pr-review` | only agents hired with `--rank senior` |

Use ranks to route expensive steps to a frontier model and keep the rest on a cheaper or local
one.

## 4. Run it

Your flow's own worker serves the `.run()` steps:

```typescript
// flows/worker.ts
import { review } from "./pr-review.js"

const worker = review.worker() // reads ZEEBE_ADDRESS, default http://localhost:26500
process.on("SIGINT", () => void worker.stop())
await worker.done
```

The workforce serves the `.agent()` steps. Start both, then an instance:

```sh
casen agent work                  # every hired agent, until Ctrl+C
npx tsx flows/worker.ts
casen process-instance create --data '{"processDefinitionId":"pr-review","variables":{"repo":"acme/api","prKey":"42"}}'
```

For each job, the workforce renders the task's prompt with the instance's variables, runs the
CLI, and completes the job with what the CLI printed, under the step's `result` variable. A
non-zero exit fails the job with the CLI's stderr, and the engine retries it until the task's
retries run out. A prompt that names a missing variable fails the job without retries, because
no retry can fix it.

Stop the workforce with Ctrl+C: jobs in progress are handed back to the engine at once, with
their retries unchanged. If the process dies instead, the engine hands the jobs out again when
their locks expire.

## Durable waits

`.waitFor()` parks the instance on a message, for as long as it takes:

```typescript
  .waitFor("ci-green", { correlationKey: "prKey", message: "ci-passed" })
```

Publish the message when the outside event happens — from a CI webhook, for example:

```sh
casen message publish --data '{"name":"ci-passed","correlationKey":"42"}'
```

Nothing holds a worker, an agent slot or a context window while the instance waits.

## Security

The workforce runs the command you hired with the arguments you gave it. If those arguments let
the agent run tools or skip permission prompts, it can do that on this machine, in `--cwd`.

The prompt it gets is the step's template filled with process variables, and variables come from
whoever can start instances or publish messages on the engine. Only run a workforce against an
engine you trust, give each agent the narrowest tool permissions its role needs, and prefer a
dedicated working directory or container for agents that can write.

---

## Documentation — Packages

### @bpmnkit/core

Fluent process builder, BPMN 2.0 parser/serializer, auto-layout, and AI-compact format.

Source: https://bpmnkit.com/docs/packages/core

## Overview

`@bpmnkit/core` is the foundation of BPMN Kit. It provides everything needed to work with
BPMN 2.0 programmatically:

- **Fluent builder** — chain method calls to construct any process shape
- **Parser/serializer** — round-trip BPMN 2.0 XML, keeping unmodelled content verbatim
- **Auto-layout** — Sugiyama algorithm assigns coordinates automatically
- **Compact format** — token-efficient AI-friendly intermediate representation
- **DMN support** — parse, build, and export DMN 1.3 decision tables

Zero runtime dependencies. ESM-only. Runs in browsers, Node.js, Deno, Bun, and edge runtimes.

## Installation

```sh
pnpm add @bpmnkit/core
```

## API Reference

### `Bpmn.createProcess(id, name?)`

Returns a `ProcessBuilder` with the given process ID and optional name.

```typescript
const builder = Bpmn.createProcess("my-process", "My Process");
```

### `Bpmn.continueProcess(definitions, processId)`

Continue an existing model instead of generating a replacement for it. `build()` returns *that
document* with the named process's contents replaced, so other processes, the collaboration,
lanes, diagram interchange, root elements and unmodelled content all survive. The input is not
mutated.

```typescript
const updated = Bpmn.continueProcess(Bpmn.parse(xml), "order-process")
  .insertAfter("validate")
  .serviceTask("notify", { name: "Notify", taskType: "notify" })
  .build();
```

Also available as `ProcessBuilder.from(definitions, processId)`.

**`.at(nodeId)`** continues from a node whose path is open — no outgoing sequence flow, or a
gateway, where several outgoing flows are the point. It refuses a node that is not directly in
that process (a node inside a sub-process means building that sub-process), an end event, and a
node that would gain a second outgoing flow — that is an uncontrolled split, and almost always
means you wanted to insert.

**`.insertAfter(nodeId)`** splices what you build next into the path leaving an existing node:
`validate → end` becomes `validate → notify → end`. The existing flow keeps its **id and its
target** and only changes where it starts, so an edge nobody asked to move keeps its identity
in the diagram and in a diff. It refuses a node with no outgoing flow, and one with several,
where "after" is ambiguous.

Which of the two you mean is not guessable, so it is not guessed.

**Continuing never infers gateways.** `ProcessBuilder` normally inserts join gateways for
branches you build; on a parsed model that reads the whole topology and retargets edges you
never touched, so continue mode does not do it. A branch that needs a join here says so with
`.connectTo(joinId)`. `build()` refuses outright if anything would rewire a sequence flow the
document already had.

**Diagram interchange is not regenerated.** Existing shapes keep their positions, and elements
you add have none until `.withAutoLayout()` or a later `applyAutoLayout()` gives them one.

`isExecutable` and the process name are left as they were unless you call `.executable()` or
`.name()`. BPMN reads an absent `isExecutable` as false, so writing the builder's default onto
a process that never carried it would make a non-executable process executable.

### `Bpmn.createDiagram(id?)`

Returns a `DiagramBuilder` for assembling multiple processes into one BPMN definitions document.
`id` defaults to `"Definitions_1"`.

```typescript
const defs = Bpmn.createDiagram("OrderSystem")
  .process("order-flow", (p) =>
    p.startEvent("s").serviceTask("t", { name: "Process", taskType: "process" }).endEvent("e"),
  )
  .process("payment-flow", (p) =>
    p.startEvent("s2").serviceTask("pay", { name: "Pay", taskType: "pay" }).endEvent("e2"),
  )
  .build();
```

### DiagramBuilder — collaborations

`.participant()`, `.message()` and `.messageFlow()` build a pooled diagram. Ids are used
verbatim, so a generated diagram can be referred to by the ids you chose.

```typescript
const defs = Bpmn.createDiagram("Order")
  .process("order", (p) => p.startEvent("o_start").serviceTask("o_send", { taskType: "send" }).endEvent("o_end"))
  .process("supply", (p) => p.startEvent("s_start").serviceTask("s_recv", { taskType: "recv" }).endEvent("s_end"))
  .participant("P_Buyer", { name: "Buyer", processId: "order" })
  .participant("P_Seller", { name: "Seller", processId: "supply" })
  .participant("P_Bank", { name: "Bank" })            // black box — no process
  .message("Msg_Order", { name: "order placed", correlationKey: "= orderId" })
  .messageFlow("MF_1", { source: "o_send", target: "s_recv", messageRef: "Msg_Order" })
  .build();
```

A message flow's `source` and `target` name either participants or flow nodes inside them —
both are valid BPMN, and `applyAutoLayout` reads either.

A diagram with no participants gets **no** collaboration element. An empty
`<bpmn:collaboration/>` is not a neutral addition: a modeler reads it as "this document is
pooled" and renders every process pool-less.

`.collaborationId(id)` renames the collaboration, which defaults to `"Collaboration_1"`.

`build()` refuses a collaboration a modeler would not open, reporting every problem at once:
a participant naming a process the diagram does not contain, two participants claiming the
same process, a duplicate id, a message flow whose endpoint does not exist or which names an
undeclared message, and — the one that is easy to write by accident — a message flow that
starts and ends in the same pool. A message flow is what crosses a pool boundary; one that
stays inside a pool should be a sequence flow.

### `Bpmn.export(definitions)`

Serializes a `BpmnDefinitions` object to a BPMN 2.0 XML string.

```typescript
const xml = Bpmn.export(definitions);
```

### `Bpmn.parse(xml)`

Parses a BPMN 2.0 XML string into a typed `BpmnDefinitions` object.

```typescript
const definitions = Bpmn.parse(xmlString);
```

### `Bpmn.makeEmpty(processId?, processName?)`

Returns minimal BPMN 2.0 XML — one process with one start event.

```typescript
const xml = Bpmn.makeEmpty("my-process", "My Process");
// Returns an XML string (not a BpmnDefinitions object)
```

### `Bpmn.SAMPLE_XML`

A constant containing a simple 3-node sample diagram (start → task → end).
Useful for demos and tests.

### `semanticHash(definitions)`

SHA-256 of the model's meaning, with the diagram excluded. Two documents that say the same
thing hash the same however they are laid out, ordered or formatted — so a changed hash means
the model changed, not that the picture moved.

```typescript
import { Bpmn, applyAutoLayout, semanticHash } from "@bpmnkit/core";

const definitions = Bpmn.parse(xml);
semanticHash(applyAutoLayout(definitions)) === semanticHash(definitions); // true
```

Excluded from the hash: diagram interchange and its `bioc`/`color` extensions,
`zeebe:modelerTemplateIcon`, and `exporter`/`exporterVersion`. Element order, attribute order
and whitespace do not affect it. `modeler:executionPlatform` **is** included — it names the
engine the model targets, so changing it is a real change.

Synchronous and dependency-free, so it works in the browser and does not force callers to
become async.

### `projectSemantics(definitions)`

The canonical, presentation-free projection `semanticHash` covers. Returns `{ value, elements }`
— the whole model as canonical JSON, plus a shallow projection per element id.

### `diffSemantics(before, after)`

What changed between two models, as `{ added, removed, changed }` keyed by element id. Changes
are attributed to the element that actually changed rather than to all of its ancestors, and
running auto-layout produces an empty diff.

```typescript
import { diffSemantics } from "@bpmnkit/core";

const { added, removed, changed } = diffSemantics(before, after);
// changed: [{ id: "Task_1", before: {...}, after: {...} }]
```

### `diffDiagram(before, after)`

What a *reviewer* would see change — `diffSemantics()` plus the layout half it deliberately
ignores, restricted to elements a canvas can actually draw.

```typescript
import { diffDiagram } from "@bpmnkit/core";

const result = diffDiagram(before, after);
result.added;    // ids only in `after`
result.removed;  // ids only in `before`
result.changed;  // same element, different semantics
result.moved;    // same semantics, different place on the canvas
result.total;
result.planes;   // per-plane breakdown — a change inside a collapsed sub-process
                 // is invisible in a viewer until the reader drills into it
```

`moved` is why this exists. The semantic hash drops all diagram interchange — that is what
makes it stable across a re-layout — so a task somebody dragged reads as no change at all in
`diffSemantics()`. Here the geometry is compared separately from DI (bounds, waypoints, label
placement, and flags such as collapsed/expanded). An element that changed *and* moved is
reported as changed, since a semantic change is what a reviewer needs first.

An element with nothing to draw on either side is left out, so a changed `targetNamespace`
cannot inflate a count against nothing on screen.

The same comparison is [`casen diff bpmn`](/docs/cli/diff) on the command line,
`createBpmnDiff()` in `@bpmnkit/plugins` on a pair of canvases, and *Compare Diagram with
HEAD* in the [VS Code extension](/docs/guides/vscode).

### `applyBpmnOperations(definitions, operations, options?)`

Applies edit operations to the full model. The operation vocabulary is the same one an LLM
produces; applying it here rather than to a `CompactDiagram` means an edit touches only what it
names and leaves the document's pools, lanes, data wiring and Zeebe detail alone.

```typescript
import { applyBpmnOperations } from "@bpmnkit/core";

const { definitions, applied } = applyBpmnOperations(parsed, [
  { op: "rename", id: "Task_1", name: "Approve invoice" },
  { op: "update", id: "Task_1", patch: { jobType: "approve" } },
]);
```

**Strict by default.** An operation naming an element that does not exist throws an
`OperationError` and nothing is applied — the previous implementation skipped such operations
silently, so a patch with a misspelled id reported success and changed nothing. Pass
`{ strict: false }` to get `{ definitions, applied, problems }` instead and decide for
yourself. The input is never mutated either way.

### `ensureZeebeExtension(owner, extension)`

Finds a Zeebe extension element on a flow element, creating it if absent, and refuses a
placement the Zeebe schema does not allow. Use it instead of pushing onto `extensionElements`
directly: the push cannot fail, so `zeebe:calledDecision` on a service task becomes a deploy
error in Camunda rather than a throw where it was written.

```typescript
import { ensureZeebeExtension, ZeebePlacementError } from "@bpmnkit/core";

ensureZeebeExtension(serviceTask, "zeebe:taskDefinition").attributes.type = "worker";
ensureZeebeExtension(serviceTask, "zeebe:calledDecision"); // throws ZeebePlacementError
```

`ZeebePlacementError` carries `ownerElement`, `extension` and `allowedOn`, so the message
names the elements that *would* have been valid.

`isZeebePlacementAllowed(ownerElement, extension)` answers the same question without throwing,
and `ZEEBE_PLACEMENT` is the table itself — extension name to the element names that may own it.

The table is generated from `zeebe.json`'s `meta.allowedIn` (`zeebe-bpmn-moddle`, MIT),
resolved against the BPMN type graph, so it states the schema's rules rather than ours. **An
extension the schema says nothing about is allowed**: the descriptor declares no owner for
`zeebe:subscription` or `zeebe:properties`, and inventing a rule there would reject valid
documents. Non-`zeebe:` extensions are not checked at all.

`applyBpmnOperations` runs the same check, and reports a misplaced extension as an ordinary
operation problem — checked before anything is written, so the element is left untouched and
the rest of the batch still applies.

### `reconcileCompact(definitions, compact, options?)`

Applies a `CompactDiagram` to an existing model as a set of changes. Elements that already
exist are patched in place and keep their extensions, new ones are inserted, and ones the input
no longer mentions are removed — where `expand(compact)` would rebuild the whole document and
discard everything the compact form cannot describe.

Processes are only added, never removed: sending one process of a multi-process document means
"this is how that process should look", not "delete the others".

### `compactify(definitions)`

Projects a `BpmnDefinitions` object onto a `CompactDiagram` — a small JSON object suitable
for LLM prompts. **Lossy:** it keeps topology, names, `<bpmn:documentation>` and the common
Zeebe bindings, and drops collaborations, participants, message flows, lanes, data stores,
artifacts, root-level messages and errors, multi-instance loop characteristics, full
`zeebe:ioMapping` entries and diagram interchange.

A sequence flow leaving an exclusive, inclusive or complex gateway carries `isDefault: true`
when the gateway names it in `bpmn:default`. It sits on the flow rather than on the gateway
because that is where its alternative, `condition`, sits — a model writing the branches of a
decision marks one of them instead of pointing back at a flow id. `expand` turns it into the
attribute; a flow marked `isDefault` that leaves anything else, or a gateway with two of them,
throws rather than being dropped, because a lost default is a gateway that deadlocks the first
time every condition is false.

`documentation` is carried on every element and on the process itself, because in Camunda 8 it
is not decoration: on an ad-hoc sub-process child it is the tool description handed to the LLM,
and on a start event it is where the process input contract is written. It had been dropped, so
a single `rename` operation cost a file the documentation of every element in it.

```typescript
import { compactify } from "@bpmnkit/core";

const compact = compactify(Bpmn.parse(xml));
```

### `expand(compact)`

Builds a `BpmnDefinitions` object from a `CompactDiagram`. It restores only what the compact
form carries, so `expand(compactify(definitions))` is not `definitions` — use this to build a
model from a compact definition, not as a round trip for a file you need to keep.

```typescript
import { expand } from "@bpmnkit/core";

const definitions = expand(compactDiagram);
const xml = Bpmn.export(definitions);
```

Every element type the model knows expands to itself, data elements included. The switch is
exhaustive, so a new `BpmnElementType` fails the build here rather than silently arriving as a
`task` — which is how `dataObject`, `dataObjectReference` and `dataStoreReference` were lost.

`expand` throws when the diagram cannot be valid BPMN. The cases are:

- a flow that names an element outside its own scope (a sub-process's flows see only that
  sub-process's children)
- a boundary event without a host in the same scope
- a duplicate id, across elements, flows and processes
- a missing element or flow id
- an unknown `eventType`

The error lists every problem in one message. It does this so that a diagram written by a language
model can be sent back with the list instead of being turned into XML that a modeler rejects later.

### `createCompactStream(options?)`

Reads a diagram out of a model's token stream, so it can be rendered while it is still being
written. A model emits a diagram one character at a time, and the outermost `}` — the one
`JSON.parse` waits for — is the last character it sends, so the seconds before it arrives are
unusable to everything downstream.

This does not parse the document. It takes complete `{…}` literals as they close and keeps the
ones shaped like a `CompactElement` or a `CompactFlow` — the innermost objects, and therefore
the first to finish.

```typescript
import { createCompactStream } from "@bpmnkit/core";

// `base` is the diagram being edited, so a frame shows the whole process rather
// than the fragment the model is adding to it. Omit it to build from nothing.
const stream = createCompactStream({ base: currentDiagram });

for await (const chunk of tokens) {
  const frame = stream.push(chunk); // null until the frame changes
  if (frame) canvas.loadDefinitions(frame, { keepViewport: true });
}
```

Not parsing is also what makes it indifferent to what it is reading: a tool-call argument, a
fenced JSON block in an assistant's prose, and the body of a code-mode snippet all carry the
same literals, and none of them has to be valid as a whole.

**Frames are advisory.** Every one is a guess at an unfinished document, and the caller is
expected to have an authoritative result coming. `push` never throws on input, drops what it
cannot place, and strips `isDefault` from a flow rather than failing when the gateway it claims
has not been written yet — a preview without the marker beats no preview. Use the model's
finished output, not a frame, as the thing you save or deploy.

A single pass over a brace stack reads each character once and considers each literal once,
innermost first, so a sub-process is seen after the children it reclaims from the top level.
On a recorded Claude run writing a seven-element order process, the first renderable frame
arrived 16% of the way into the tool argument, with 15 frames following.

### `parseProcessText(text)` and `createProcessTextStream()`

A line format for a model to write a new process in. It costs about a quarter of the output
tokens of minified compact JSON. A path is written once as `a > b > c`, a node is declared inline
the first time it is used, and the parser adds what the model would otherwise spend tokens on.
`PROCESS_TEXT_GUIDE` is the part of a system prompt that teaches the format (~600 tokens,
example included).

```text
# Expense approval
start[start Expense submitted] > check[xor Amount over 1000?]
check >(Yes: amount > 1000) review[user Review expense] > pay[service Pay expense] > done[end Expense paid]
check >(No: default) auto[service Approve automatically] > pay
failed[boundary:error Payment failed | on=pay] > notify[send Notify submitter] > notice[end Payment failed]
```

Parallel work, deadlines and steps run per item are taught as rules, not in the example:
`glm-4.7-flash` copied example lines such as "Email each approver" into processes that never
asked for them.

Attributes after `|`:
- `on=<task>` puts a boundary event on its task, and `nonint` makes it non-interrupting;
- `job=<type>` sets the job type;
- `each=<list>` runs a task or sub-process once per item of the list variable, each instance
  getting its item in the singular (`each=approvers` → `approver`);
- `after=<duration>` sets a timer's duration, ISO 8601 or `5m`, `2 hours`, `1 day`. Without
  it, a duration in the timer's name is read ("Wait 5 minutes" → `PT5M`).
- `result=<variable>` names the variable a task's result goes to;
- `feel=<expression>` makes the step a script task that evaluates the FEEL expression into
  `result=` (its id when there is none), written as `zeebe:script`. It comes last: the
  expression takes the rest of the attributes, spaces and commas included. An expression that
  does not parse as FEEL is kept and reported in `problems`.

The guide tells the model that a step working only on process data — counting, summing,
filtering, formatting — is such a script task, never a service task:
`count[script Count open issues | result=openCount feel=count(issues[state = "open"])]`.

A boundary leads only to the handling of what it catches. When a model writes the work that
follows a task through its boundary instead (`err > count > post`), the parser moves those
ways out onto the task — all but the ones named for handling (failure, error, notify, retry,
…; the first when none is) — and drops a bare end event the task led to.

An attribute written before the `|` (`late[boundary:timer on=pay]`) is read all the same.
`after=` on an event that is not a timer makes it one, and a boundary without `on=` that one
task is drawn into (`send > wait[boundary:timer …]`) goes on that task.
Change scripts read `result=` and `feel=`, but not `each=` and `after=` yet.

```typescript
import { expand, Bpmn, parseProcessText, PROCESS_TEXT_GUIDE } from "@bpmnkit/core";

const { diagram, problems, fixes } = parseProcessText(modelOutput);
const xml = Bpmn.export(expand(diagram));
```

`parseProcessText` never throws, and its diagram always expands. It also keeps the structural
rules `lintDiagram` checks — including bpmnlint's recommended set — whatever the model wrote.
Text it cannot use, and anything it has to leave out, is returned in `problems` with its line
number. What it adds or changes is listed in `fixes`:

- flow ids are generated
- a line that ends in an arrow continues on the next line, a note after a line's last node
  (`(ADDED)`) is ignored, and a second `|` in the attributes is a separator
- an id used in a flow but never declared becomes a task named from it, or the gateway its
  name is a kind of (`pick > and`)
- an id declared again after an arrow, with a different kind or name, is a new node (`done_2`),
  and later bare references mean the newest; restated at the start of a line, it is the node
  already there. A name of three words or more makes a new node even when its kind word is
  unknown (`send[post Slack message to #support]`)
- a number written as an id (`1[service …]`) becomes `n1`; a numbered list (`1. a > b`) is
  still prose
- after an arrow, a kind and a name without brackets (`… > end Order shipped`) declare a node;
  at the start of a line they stay prose
- a line that starts with an arrow continues the last node of the path above it, and a space
  between an arrow and its label (`gw > (No: default) b`) is allowed
- a step whose name says it is done for each or every item ("Send email to each stakeholder") runs
  once per item of the list (`=stakeholders`); "every day" and other time words do not count
- a DMN decision whose outcomes are not labelled splits with an exclusive gateway, not in parallel
- steps in a row between an and split and an and join (`fork[and] > a > b > joined[and]`) run in
  parallel; a catch event with `on=` a task is a boundary event; a named and node with `each=` is
  a task run per item
- a bracket left open is closed where the name plainly ends: at a `)` before the next arrow,
  before the next arrow, or at the end of the line (`start[start Order) > …`)
- a missing start event is added, and a start event left unconnected leads to the first path;
  only the first blank start event is kept
- a branch drawn into a boundary event continues to what the boundary leads to, and a flow from a
  node to itself is refused
- **every node lies on a path from a start event.** A task or gateway nothing leads to continues
  the latest path written before it that stops short of an end event — most often the model left
  out one arrow. What still cannot be reached, such as a boundary on a task that was never
  declared, is left out and reported; it is never drawn as a loose node
- an end event is added after every path that stops elsewhere, and a loop with no way out gets
  an exit branch from its decision; a loop with no decision loses the flows that close it
- a link event in a path becomes a plain event, since the format cannot name its partner
- a catch or boundary event written without a trigger becomes a message event, so it deploys.
  A catch event named for a call it makes ("Send to SQS") becomes a service task instead
- an id written with spaces before its bracket (`call back[service …]`) is read as one id,
  `call_back`
- a gateway with one way in and one way out — a question answered only one way — is removed;
  an event-based gateway waiting for one event becomes a catch event
- a task or event with several ways out gets a split gateway: exclusive when the branches are
  labelled, event-based when they all wait (at least one on a catch event, and receive tasks
  among them become message catch events), and parallel otherwise
- branches that meet at a task, an event or a gateway that also splits are joined first, by a
  gateway of the type they were split with: parallel branches get a parallel join
- a condition that is not FEEL (`applicant is eligible`) moves into the branch label and is
  reported, so it cannot fail at deploy time
- every xor/or split has one default — the branch labelled `No`, `Otherwise`, `Rejected` and the
  like, or else the last unconditioned one — and every other branch a FEEL condition. A branch
  written in prose gets one on a variable named for the gateway's question:
  `Status approved?` with `Yes` becomes `= statusApproved = true`
- flows out of anything but a decision carry no condition or label
- an unnamed event, task or decision is named from its id
- a service or send task without `job=` takes its id as job type, and a rule task its id as
  decision id

Some of those fixes are guesses only the reader can confirm, and `questions` puts them as
questions, in the order of the text. Each has the element it is about, the question, ready
answers where there are any, and a `draft` for the reader to finish. An answer is written as a
change request, for a model to apply to the diagram:

- a condition made up on a variable named for the question: what data decides it?
- a default branch picked because none was marked, or none reads as "otherwise": is it the
  right fallback? The other branches are the answers
- unlabelled branches split in parallel: do they really run at the same time? "Only one of them"
  or "One after the other"
- a question answered one way only, and removed: what happens otherwise?
- a task left out because nothing leads to it: where does it belong?
- a loop given an exit: when does it end?
- an event written without a trigger, made a message event: is it a timer, a signal, or nothing?

```typescript
const { questions } = parseProcessText(modelOutput);
// [{ elementId: "ok", text: '"Status approved?" decides on "statusApproved", a variable the
//    diagram made up. What data decides it?', options: [], draft: 'At "Status approved?", decide on ' }]
```

`createProcessTextStream()` reads the same format while it arrives. It reads each finished line
as it arrives, so every frame is built from whole facts. `push(chunk)` returns a laid-out frame,
or `null` when nothing new is drawable. `end()` returns what `parseProcessText` would.

### `writeProcessText(defs)` and `parseProcessDelta(text)`

The other direction, for changing a diagram that already exists. `writeProcessText` writes the
first process of a document in the line format, so a model can read it. Each node is written
under a short readable alias (`review_application` for `Activity_0x9k2lm`), and the map back to
the real ids comes with the text. Only what the format can express is written: flow nodes and
sequence flows, with names, triggers, `job=` and conditions. Lanes, data objects, annotations
and the inside of a sub-process are left out, so a change cannot reach them.

The model answers with a **change script** (`PROCESS_DELTA_GUIDE`): the same line format, but
only what changes. An existing node is named by its id; declaring it again changes its kind or
name; `- x` and `- a > b` remove; `@2 x y` says which feedback item a change answers.

```typescript
import { PROCESS_DELTA_GUIDE, PROCESS_TEXT_GUIDE, parseProcessDelta, writeProcessText } from "@bpmnkit/core";

const { text, aliases } = writeProcessText(defs);
// system: PROCESS_TEXT_GUIDE + PROCESS_DELTA_GUIDE; user: text + the feedback
const delta = parseProcessDelta(modelOutput);
// { nodes, flows, removedNodes, removedFlows, addressed, problems }
```

`parseProcessDelta` never throws and resolves nothing: it reads the script. Apply it with
`applyProcessDelta` from `@bpmnkit/editor/headless`, which keeps the diagram's layout.

### Connectors: `with` lines

Both formats take `with` lines, which configure a node as a Camunda connector:

```
with notify: slack chat.postMessage | token={{secrets.SLACK_TOKEN}} | data.channel=#ops | data.text== "Order " + orderId
with fetch: http GET https://api.example.com/orders | result=order: response.body
```

A line names a node by its id, then the connector's alias, its operation and its inputs as
`key=value` (`key==expr` for FEEL). Path lines are unchanged, so a diagram still streams and keeps
every structural rule.

- **Parsing.** `parseProcessText` returns the lines as `connectors`, each with the element it
  names. `parseProcessDelta` returns them as `connectors` too. Neither applies them.
- **Applying.** `applyConnectorLines` from
  [`@bpmnkit/core/connectors`](/docs/packages/connectors#with-lines) applies them, outside
  core's main entry, so the catalog is only bundled where it is used.
- **Writing.** `writeProcessText(defs, { connectorLine: connectorLineFor })` writes an
  element's connector back as a `with` line, so a model that changes the diagram keeps it.
- **Secrets.** `listSecrets(definitions)` lists every secret the diagram's configuration
  reads, with the elements that read it. It covers `{{secrets.NAME}}`,
  `camunda.secrets.NAME` and message correlation keys, so whoever deploys knows what to
  create first.
- **API index calls.** `with charge: http POST /v1/customers | api=stripe` calls an endpoint of
  the [API index](/docs/packages/connector-gen#api-index). Its base URL, authentication and
  headers come from the index when the lines are applied with `{ apis }`.

### `retypeElement(element, type)`

Returns a copy of a flow element with a different `type`, keeping its id, name, documentation
and — crucially — its incoming and outgoing sequence flows. Use this to change a task's type
instead of removing and re-adding the element, which drops the wiring.

```typescript
import { retypeElement } from "@bpmnkit/core";

const index = process.flowElements.findIndex((el) => el.id === "charge");
process.flowElements[index] = retypeElement(process.flowElements[index], "manualTask");
```

Nested content is carried between container types, and a multi-instance marker between types
that both allow one. Zeebe extensions the new type cannot legally hold are dropped, using the
same placement table `ensureZeebeExtension` enforces — so a `serviceTask` retyped to
`manualTask` does not keep a job worker the engine would refuse.

### `createFlowElement(id, type, options?)`

Builds an empty flow element of any `BpmnElementType`, with the right shape for that type.
This is the single place that mapping lives; the fluent builder uses it too.

### Element catalog

`ELEMENT_TYPE_GROUPS` maps every `BpmnElementType` to one of `event`, `task`, `gateway`,
`container` or `data`, with `allElementTypes()` and `elementTypesInGroup(group)` over it. Tool
schemas and prompts render their type lists from this rather than hard-coding one — a
hand-written list is how the MCP schema came to advertise 18 types while the compact path
accepted 23.

### `layoutProcess(process)`

Runs the Sugiyama auto-layout algorithm on a `BpmnProcess` object.
Returns a `LayoutResult` with element positions.

```typescript
import { layoutProcess, ELEMENT_SIZES } from "@bpmnkit/core";

const result = layoutProcess(process);
// result.elements: Map<id, { x, y, width, height }>
// result.flows: Map<id, waypoint[]>
```

### ProcessBuilder methods

All builder methods return `this` for chaining.

| Method | Description |
|---|---|
| `.startEvent(id, options?)` | Add a start event |
| `.endEvent(id, options?)` | Add an end event |
| `.serviceTask(id, options?)` | Add a service task |
| `.userTask(id, options?)` | Add a user task |
| `.scriptTask(id, options?)` | Add a script task |
| `.sendTask(id, options?)` | Add a send task |
| `.receiveTask(id, options?)` | Add a receive task |
| `.businessRuleTask(id, options?)` | Add a business rule task |
| `.manualTask(id, options?)` | Add a manual task — work done outside the engine, no job worker |
| `.task(id, options?)` | Add an abstract task with no Zeebe extensions |
| `.exclusiveGateway(id, options?)` | Add an XOR gateway |
| `.parallelGateway(id, options?)` | Add a parallel gateway |
| `.inclusiveGateway(id, options?)` | Add an inclusive gateway |
| `.eventBasedGateway(id, options?)` | Add an event-based gateway |
| `.complexGateway(id, options?)` | Add a complex gateway (aspirational — Zeebe does not execute these) |
| `.subProcess(id, builder, options?)` | Add an embedded sub-process |
| `.adHocSubProcess(id, builder, options?)` | Add an ad-hoc sub-process — its children are **not** auto-chained, see below |
| `.eventSubProcess(id, builder, options?)` | Add an event sub-process (emits `subProcess triggeredByEvent="true"`) |
| `.transaction(id, builder, options?)` | Add a transaction sub-process (atomic scope) |
| `.callActivity(id, options?)` | Add a call activity |
| `.intermediateCatchEvent(id, options?)` | Add a catch event |
| `.intermediateThrowEvent(id, options?)` | Add a throw event |
| `.branch(id, builder)` | Define a gateway branch |
| `.boundaryEvent(id, options)` | Attach a boundary event to the previous task |
| `.withBoundary(id, options, handler)` | Attach a boundary event and build its error/timeout path; cursor auto-restores to the main flow after the handler |
| `.defaults(options)` | Set process-wide defaults (e.g. `{ serviceTask: { retries: "5" } }`) applied to all subsequent tasks |
| `.disconnectedStartEvent(id?, options?)` | Add a start event with no auto-connection to the current cursor — alias for `addStartEvent` |
| `.withAutoLayout()` | Apply Sugiyama layout before building |
| `.build(options?)` | Return the completed `BpmnDefinitions`. Pass `{ explicitJoins: true }` to refuse inferred join gateways — see below |

Every BPMN element type the model knows is reachable from a builder chain, except the three
data types (`dataObject`, `dataObjectReference`, `dataStoreReference`) — those are wired by
data associations rather than sequence flows, so the chain has nowhere to put them. A
compile-time table, `BUILDER_COVERAGE`, holds the SDK to that: adding an element type without
a builder method fails the build. Run `pnpm --filter @bpmnkit/core check:builder` to print it.

### Ad-hoc sub-processes: children are a set, not a chain

Sequential calls in a builder chain auto-connect with sequence flows. Inside
`.adHocSubProcess()` they do not: BPMN defines an ad-hoc sub-process's children as an unordered
set of independently-invocable activities, and Camunda 8's agentic AI runtime reads that
structurally — a child *without* an incoming flow is an LLM-invocable tool, a child *with* one
is part of an internal sub-flow and not a tool at all.

```typescript
.adHocSubProcess("agent", (s) => {
  s.serviceTask("listUsers",  { taskType: "io.camunda:http-json:1" });
  s.serviceTask("loadUser",   { taskType: "io.camunda:http-json:1" });
  s.serviceTask("createUser", { taskType: "io.camunda:http-json:1" });
}, { name: "Handle request" })
// → three tools, no sequence flows, no <bpmndi:BPMNEdge> between them
```

Auto-chaining them produced a file that lints clean and deploys, while the agent saw one tool
and a two-step sub-flow — so the default is off rather than opt-out.

An internal sub-flow inside the container stays expressible: say so with `.connectTo()`, which
still creates a flow from the cursor.

```typescript
.adHocSubProcess("agent", (s) => {
  s.serviceTask("listUsers", { taskType: "io.camunda:http-json:1" });   // a tool
  s.serviceTask("step1", { taskType: "work" }).connectTo("step2");      // an internal sub-flow
  s.serviceTask("step2", { taskType: "work" });
})
```

Each child's LLM-facing description is its `documentation`, which every builder method accepts:

```typescript
s.serviceTask("listUsers", {
  taskType: "io.camunda:http-json:1",
  documentation: "Call this to retrieve all users. Returns id, name, email.",
});
```

### Joins: inferred by default, or declared

Where several branches of one gateway reach the same element, `build()` inserts a matching
join gateway for you. That is a help when you are reading the chain you just wrote, and a trap
for generated code, which cannot see the element it did not emit.

```typescript
const defs = builder.build({ explicitJoins: true });
// Error: Inferred join gateways: gw_join. Declare them with .connectTo(joinId),
// or drop { explicitJoins: true } to keep the inference.
```

The error names the gateway it would have added, which is the id you pass to `.connectTo()`.

A join you declare only counts if it **matches the split**: an exclusive split converging on a
parallel gateway is not the gateway inference would have added, so it is still inferred — and
with `explicitJoins` that refusal is the only thing that tells you.

`Bpmn.continueProcess()` never infers joins at all, whatever this option says. Inference reads
the whole topology, and on a document you were handed that means rewriting edges you never
touched.

`{ strict: true }` was the former name for this option. It was removed in 1.0.0 — "strict"
says nothing about what it is strict *about*, and `applyBpmnOperations` takes a `strict` that
means something else entirely. Rename it to `explicitJoins`; the behaviour is identical.

## Writing files — `@bpmnkit/core/node`

Anything that touches the filesystem lives behind the `@bpmnkit/core/node` subpath, so
importing `@bpmnkit/core` itself never pulls `node:` builtins into a browser bundle.

### `writeBpmn(definitions, options)`

The only supported way to write a BPMN file, and the only one that checks what it wrote.
Before anything reaches disk it serialises the model, **parses the result back**, and compares
the semantic hashes. If they differ the write is refused and nothing is written.

```typescript
import { writeBpmn } from "@bpmnkit/core/node";
import { WriteError, WriteVerificationError } from "@bpmnkit/core";

const result = await writeBpmn(definitions, {
  output: "flow.bpmn",
  force: false,        // default — refuses rather than replace an existing file
  layout: "preserve",  // default — "auto" regenerates the diagram first
});

result.destination;    // absolute path written
result.semanticHash;   // the model's hash, verified after reading it back
result.outputSha256;   // digest of the exact bytes on disk
result.changes;        // what this write changed about the file it replaced
```

The file appears complete or not at all: contents go to a temporary file in the destination's
own directory and are then linked or renamed into place, so an interrupted write cannot leave
a half-written model behind. Two concurrent writes to the same new path cannot both succeed.

`WriteVerificationError` carries a `changes` field naming the elements that diverged.
`WriteError` means the destination exists and `force` was not given, or the filesystem refused.

**What the check does not cover.** It compares the model in memory against the model read back
from the output, so it catches the serialiser losing something. It cannot catch the *parser*
having dropped something on the way in — content the parser never saw is absent from both
sides. That is what the round-trip corpus gate covers, and there is deliberately no option to
skip verification: turning it off would only ever be used to get past the bug it exists to
report. If you want unchecked serialisation, `Bpmn.export()` still returns a string.

### `exportPreserving(original, definitions)`

Writes a model back over the file it came from, changing as little as possible.

`Bpmn.export()` writes a model the way this toolkit writes models. That is the right output
for a new document and the wrong one for an existing file: the first visual edit reformats
every line, and the commit says "the whole diagram" when it means "a box moved".

Exported from `@bpmnkit/core` itself, not the `/node` subpath — it is string work, and the
caller owns the file:

```typescript
import { readFile, writeFile } from "node:fs/promises";
import { Bpmn, exportPreserving } from "@bpmnkit/core";

const onDisk = await readFile("order.bpmn", "utf8");
const edited = Bpmn.parse(onDisk);
edited.processes[0].flowElements[0].name = "Validate Order";

await writeFile("order.bpmn", exportPreserving(onDisk, edited));
// Renaming one task changes one line, not the whole file.
```

Indentation, attribute order, comments, the order children were written in, and attributes
left at their schema default all survive. Opening a file and writing it back unchanged leaves
it byte for byte.

Nothing about that is assumed, though. The model cannot represent the order a file writes its
children in — a process holds `flowElements` and `sequenceFlows` as separate lists — so each
strategy is tried, **the result is parsed back and compared against a plain write**, and the
first that reads the same is the one used. The plain write is the floor, so calling this is
never worse than not.

| Function | Takes | Returns |
| --- | --- | --- |
| `exportPreserving(original, definitions)` | the file's current text + a model | the new text |
| `exportPreservingResult(original, definitions)` | same | the text plus what it managed to keep |
| `preserveBpmnFormatting(original, updated)` | two documents as text | for a caller that already serialised, such as an editor's `exportXml()` |
| `exportDmnPreserving` / `preserveDmnFormatting` | DMN | the same treatment |
| `exportFormPreserving` / `preserveFormFormatting` | Camunda form JSON | indentation, key order and trailing newline |

This is what the [VS Code extension](/docs/guides/vscode) saves through, and what makes a
visual edit reviewable in a pull request.

Builder output is stable for the same reason: sequence-flow and root-definition ids are
derived from the model (`Flow_<source>_<target>`, `Message_<name>`, `Error_<code>`) rather
than randomly generated, so rebuilding an unchanged model produces the same file and the one
edge that changed is not buried in a diff of edges that did not.

## Connectors — `@bpmnkit/core/connectors`

The Camunda 8 out-of-the-box connector catalog and deterministic element-template
application. It sits behind its own subpath because its data is about 100 KB gzipped: code
that imports only `@bpmnkit/core` does not bundle it.

```typescript
import { applyConnectorTemplate, searchConnectors } from "@bpmnkit/core/connectors"

searchConnectors("slack")[0]?.requiredInputs // what the template will ask for

const { serviceTask, problems } = applyConnectorTemplate("io.camunda.connectors.HttpJson.v2", {
  url: "https://api.example.com/orders",
})
// serviceTask: builder options — task type, input mappings, headers, template stamp
```

`findConnectorCards(query)` answers a request with **connector cards**: one operation each,
with only the inputs it uses and the values that select it, as `formatConnectorCard` writes it
for a prompt. See [`@bpmnkit/connectors`](/docs/packages/connectors#connector-cards) for the
details.

**API cards** do the same for the REST connector and systems without a dedicated connector:
the real base URL, authentication and endpoints of an HTTP API. Core has their shape
(`ApiService`) and the functions that pick, format and apply them. The data is the
[API index](/docs/packages/connector-gen#api-index) of `@bpmnkit/connector-gen`, which is
too large for core. See [`@bpmnkit/connectors`](/docs/packages/connectors#api-cards).

The bundled templates leave out icons, groups, tooltips and placeholders, which only a
property panel draws, so an applied element carries no `zeebe:modelerTemplateIcon`.
[`@bpmnkit/connectors`](/docs/packages/connectors) has the same API with those parts added
back. It is the one to use in an editor.

## DMN Support

```typescript
import { Dmn } from "@bpmnkit/core";

// Parse DMN XML
const dmnDefs = Dmn.parse(dmnXmlString);

// Create a minimal empty decision table
const empty = Dmn.makeEmpty();

// Export back to XML
const dmnXml = Dmn.export(dmnDefs);
```

## TypeScript Types

Key types exported from `@bpmnkit/core`:

```typescript
import type {
  BpmnDefinitions,
  BpmnProcess,
  CompactDiagram,
  LayoutResult,
  ProcessBuilder,
  DiagramBuilder,
  ServiceTaskOptions,
  UserTaskOptions,
  GatewayOptions,
} from "@bpmnkit/core";
```

---

### @bpmnkit/engine

Zero-dependency BPMN simulation engine for browsers and Node.js.

Source: https://bpmnkit.com/docs/packages/engine

## Overview

`@bpmnkit/engine` is a lightweight BPMN 2.0 process *simulator* that runs entirely in the
JavaScript runtime — no external services required. It is built for tests, demos and
step-through debugging, not for running production processes.

**What the TypeScript simulator executes:**
- Service and user tasks (dispatched to registered job workers), script tasks (FEEL),
  business rule tasks (DMN); manual, send, receive and plain tasks pass straight through
- Exclusive (with default flow), parallel, inclusive and event-based gateways. An event-based
  gateway arms the message, timer and signal catch events (and receive tasks) after it; the
  first to fire takes its branch and the others are cancelled. A complex gateway splits like
  an inclusive one: every flow whose condition holds, else the default flow
- Start events: none, and signal (see `broadcastSignal`). End events: none, terminate, error,
  escalation, signal and compensation
- Intermediate catch events: timer (ISO 8601 duration, date and cycle), message, signal and
  link. Intermediate throw events: signal, escalation, link and compensation
- Boundary events: timer, message and signal — interrupting, or non-interrupting, in which
  case the activity keeps running and a timer cycle fires once per repetition — plus error and
  escalation. An error a job worker throws with `job.throwError(code, …)` is caught like one
  from an error end event
- Errors and escalations propagate outwards: a boundary event on the throwing task, then per
  scope an event sub-process of the scope and a boundary event on the activity running it, up
  to the call activity that started the instance. An uncaught error fails the instance; an
  uncaught escalation does not
- Embedded sub-processes, transactions and event sub-processes (message, timer, signal, error
  and escalation start events, interrupting or not), in the process or in a sub-process
- Call activities: when `zeebe:calledElement processId` names a process deployed in the same
  engine, it runs as a child instance. By default every parent variable is copied in and every
  child variable propagates back (`propagateAllParentVariables` / `propagateAllChildVariables`
  turn that off); output mappings pick what returns. A failed job in the child fails the
  caller. A process that is not deployed completes the call activity with an `element:warning`
  event
- Multi-instance tasks and sub-processes, parallel and sequential: `zeebe:loopCharacteristics`
  `inputCollection` / `inputElement` / `outputCollection` / `outputElement`, `loopCardinality`,
  and `completionCondition` with `numberOfInstances`, `numberOfActiveInstances`,
  `numberOfCompletedInstances` and `numberOfTerminatedInstances`. Each iteration has its own
  scope with `loopCounter`
- Ad-hoc sub-processes with a `zeebe:taskDefinition` (the AI Agent Sub-process connector),
  when a worker is registered for the job type. The job carries `adHocSubProcessElements`,
  and the worker completes it with a job result:
  `job.complete(vars, { type: "adHocSubProcess", activateElements, isCompletionConditionFulfilled, isCancelRemainingInstances })`.
  Each activated element runs in its own scope with the variables it was given. When it ends,
  `outputElement` is appended to `outputCollection` and a new job asks the worker again. A
  completion without a job result completes the sub-process
- Compensation: a compensation throw or end event runs the handlers (`isForCompensation`
  activities associated with a compensation boundary event) of the activities completed in
  its scope, including inside completed sub-processes, one after another in reverse
  completion order, and waits for them. `activityRef` limits it to one activity
- Zeebe IO mappings, and DMN decisions through `@bpmnkit/feel`

**What it does not execute.** Ad-hoc sub-processes without a task definition complete without
running their inner activities. Conditional events are not evaluated: a conditional catch
event passes straight through, and conditional boundary and start events never fire. A message
start event of a top-level process does not start instances, and transaction cancel events
are not modelled. Inclusive and complex *joins* do not wait for the other branches — each
arriving token passes through — and a complex gateway's activation condition is ignored.
Zeebe invokes compensation handlers all at once rather than in reverse order, and supports
compensation event sub-processes, which the simulator does not. In `beforeComplete` (step)
mode, timers on catch events and event-based gateways fire without waiting; boundary and
event sub-process timers keep real time. For Zeebe semantics, `@bpmnkit/engine/wasm-runner`
runs the same scenarios on the Reebe engine compiled to WebAssembly (experimental).

Zero runtime dependencies. ESM-only.

## Installation

```sh
pnpm add @bpmnkit/engine
```

## API Reference

### `new Engine()`

Creates a new engine instance. Each instance has its own process registry and running instances.

### `engine.deploy(options)`

Deploys one or more process and decision definitions:

```typescript
await engine.deploy({
  bpmn: bpmnXmlString,         // required
  forms: [formSchemaJson],     // optional: Camunda form schemas
  decisions: [dmnXmlString],   // optional: DMN decision tables
});
```

### `engine.start(processId, variables?, options?)`

Starts a new process instance:

```typescript
const instance = engine.start("my-process", {
  orderId: "ord-123",
  amount: 99.99,
});
```

**`StartOptions`:**

```typescript
type StartOptions = {
  beforeComplete?: (elementId: string) => Promise<void>;
};
```

The `beforeComplete` hook fires after a task has been executed but before the process
advances. Use it to pause for step-by-step execution or to inspect state mid-run.

### `engine.registerJobWorker(type, handler)`

Register a synchronous or asynchronous handler for service tasks of a given type:

```typescript
engine.registerJobWorker("send-email", async (job) => {
  await mailer.send({
    to: job.variables.recipient,
    subject: job.variables.subject,
  });

  // Complete the job (advances the process)
  await job.complete({ sent: true });

  // Or fail it (retries depending on retry config)
  // await job.fail("SMTP connection refused");
});
```

### `engine.broadcastSignal(name, variables?)`

Delivers a signal to every running instance of this engine, call-activity children included,
and starts an instance of every deployed process whose top-level signal start event matches.
`name` matches the signal's `name`, or its id when it has none. Returns the instances it
started. A signal throw or end event inside an instance broadcasts the same way.

```typescript
engine.broadcastSignal("shutdown", { reason: "maintenance" });
```

### `engine.getDeployedProcesses()`

Returns metadata about all deployed process definitions:

```typescript
const processes = engine.getDeployedProcesses();
// [{ id: "my-process", name: "My Process", version: 1 }]
```

## ProcessInstance

| Property | Type | Description |
|---|---|---|
| `state` | `"active" \| "completed" \| "terminated" \| "failed"` | Current lifecycle state |
| `activeElements` | `string[]` | IDs of currently active elements |
| `variables_snapshot` | `Record<string, unknown>` | Current variable state |
| `beforeComplete` | `(id: string) => Promise<void>` | Override step hook |

| Method | Description |
|---|---|
| `instance.onChange(cb)` | Subscribe to state changes |
| `instance.cancel()` | Cancel the running instance |
| `instance.deliverMessage(name, vars?, correlationKey?)` | Correlate a message to the oldest waiting subscription — catch event, boundary event, event-based gateway branch or event sub-process. `name` matches the message's name or id. With a `correlationKey`, only a subscription whose `zeebe:subscription` correlation key (on the event or its message, evaluated when the subscription opened) equals it matches. Falls through to running call-activity children. Returns whether anything received it |
| `instance.deliverSignal(name, vars?)` | Deliver a signal to this instance only |

Besides `element:entering` / `entered` / `leaving` / `left`, `variable:set`, `job:created`,
`feel:evaluated` and the `process:*` events, `onChange` reports `element:terminated` when an
interrupting event, a terminate end event or a multi-instance completion condition cancels
an element, and `element:warning` when the simulator skips something it cannot run.

## Variable Scoping

Variables follow Zeebe's scope rules:

- The process, each embedded or event sub-process, each multi-instance iteration and each
  element with an IO mapping has its own scope
- Input mappings create local variables of the element
- A result — job variables, a script or decision result, a message or signal payload, a child
  process's variables — updates the variable in the nearest scope that defines it, or creates
  it in the process scope. With output mappings, the result stays local to the element and
  only the mapped variables leave it
- A sub-process's local variables are dropped when it completes unless an output mapping
  carries them out
- `inputElement` and `loopCounter` are local to a multi-instance iteration; the
  `outputCollection` reaches the enclosing scope when the loop completes

## Timer Scheduling

Timers use `setTimeout` internally and support ISO 8601 formats:

```
PT30S       → 30 seconds
PT1H30M     → 1.5 hours
P2D         → 2 days
R3/PT1H     → repeat 3 times, every hour
2026-12-01T09:00:00Z  → fire at absolute date
```

Call `parseDurationMs(str)` from `@bpmnkit/engine` to convert duration strings
to milliseconds in your own code.

---

### @bpmnkit/api

Fully-typed Camunda 8 REST API client with OAuth2, caching, and retry.

Source: https://bpmnkit.com/docs/packages/api

## Overview

`@bpmnkit/api` is a complete TypeScript client for the Camunda 8 Orchestration Cluster
REST API:

- **180 typed methods** across 30+ resource classes
- **Auth**: OAuth2, Bearer token, Basic, and no-auth
- **LRU+TTL cache** for read-heavy operations
- **Exponential backoff** with configurable retry
- **TypedEventEmitter** for observability hooks
- Zero transitive runtime dependencies

## Installation

```sh
pnpm add @bpmnkit/api
```

## Client Configuration

```typescript
import { CamundaClient } from "@bpmnkit/api";

const client = new CamundaClient({
  baseUrl: "https://api.cloud.camunda.io",
  auth: {
    type: "oauth2",
    clientId: process.env.CAMUNDA_CLIENT_ID,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
    audience: process.env.CAMUNDA_AUDIENCE,
    tokenUrl: process.env.CAMUNDA_TOKEN_URL,
  },
  // Optional:
  cache: {
    maxSize: 500,     // LRU cache size (default: 200)
    ttlMs: 30_000,    // cache TTL in ms (default: 60_000)
  },
  retry: {
    maxAttempts: 3,   // default: 3
    initialDelayMs: 200,
    maxDelayMs: 5_000,
  },
});
```

## Resource Namespaces

All methods are grouped by resource type:

| Namespace | Methods |
|---|---|
| `client.process` | deploy, startInstance, listInstances, getInstance, cancel, migrate |
| `client.jobs` | activate, complete, fail, throwError, activateAndProcess |
| `client.incidents` | list, resolve, get |
| `client.variables` | list, get, update |
| `client.decisions` | evaluate, list, getInstance |
| `client.messages` | publish, correlate |
| `client.signals` | broadcast |
| `client.userTasks` | list, get, complete, assign, claim |
| `client.users` | list, get, create, delete |
| `client.groups` | list, get, create, assignMember |
| `client.authorizations` | list, create, delete |

## Process Operations

```typescript
// Deploy
const deployed = await client.process.deploy({
  resources: [{ content: bpmnXml, name: "my-flow.bpmn" }],
});

// Start instance
const instance = await client.process.startInstance({
  bpmnProcessId: "my-flow",
  variables: { customerId: "cust-001" },
});

// List active instances
const { items } = await client.process.listInstances({
  state: "ACTIVE",
  bpmnProcessId: "my-flow",
});

// Cancel instance
await client.process.cancel({
  processInstanceKey: instance.processInstanceKey,
});
```

## Job Workers

```typescript
// Activate and handle jobs in a poll loop
const worker = await client.jobs.activateAndProcess({
  type: "send-email",
  maxJobsToActivate: 10,
  timeout: 60_000,          // job lock duration in ms
  worker: "email-worker-1",

  handler: async (job) => {
    try {
      await sendEmail(job.variables);
      await client.jobs.complete({
        jobKey: job.key,
        variables: { emailSent: true },
      });
    } catch (err) {
      await client.jobs.fail({
        jobKey: job.key,
        errorMessage: String(err),
        retries: job.retries - 1,
      });
    }
  },
});

// Stop polling
worker.close();
```

## Incident Resolution

```typescript
// Find all incidents for a process instance
const { items: incidents } = await client.incidents.list({
  processInstanceKey: instance.processInstanceKey,
});

// Fix the problem in your code, then resolve
for (const incident of incidents) {
  await client.incidents.resolve({ incidentKey: incident.key });
}
```

## Message Correlation

```typescript
await client.messages.publish({
  messageName: "payment-confirmed",
  correlationKey: "ord-456",
  variables: {
    paymentMethod: "card",
    confirmedAt: new Date().toISOString(),
  },
  timeToLive: 60_000,   // ms — how long to wait for a matching instance
});
```

## Observability Events

```typescript
type ClientEvent = "request" | "response" | "error" | "retry" | "token-refresh";

client.on("request",  (e) => logger.debug(e.method, e.url));
client.on("response", (e) => metrics.histogram("api.latency", e.durationMs));
client.on("error",    (e) => logger.error(e.status, e.url, e.body));
client.on("retry",    (e) => logger.warn(`Retrying ${e.url} (attempt ${e.attempt})`));
```

---

### @bpmnkit/canvas

Zero-dependency SVG BPMN viewer with pan/zoom, dark/light theme, and plugin API.

Source: https://bpmnkit.com/docs/packages/canvas

## Overview

`@bpmnkit/canvas` is a lightweight BPMN 2.0 diagram viewer that renders to SVG.
It has no runtime dependencies and works in any browser environment.

**Features:**
- SVG rendering of all standard BPMN 2.0 element types
- Pan and zoom (mouse wheel, touch pinch, keyboard)
- Dark and light theme
- Plugin API for extending rendering and behavior
- `diagram:load` and `diagram:change` events

## Installation

```sh
pnpm add @bpmnkit/canvas
```

## Basic Usage

```typescript
import { BpmnCanvas } from "@bpmnkit/canvas";

const canvas = new BpmnCanvas({
  container: document.getElementById("canvas"),
  theme: "dark",   // "dark" | "light"
});

await canvas.loadXML(bpmnXml);
```

## Options

```typescript
type CanvasOptions = {
  container: HTMLElement;
  theme?: "dark" | "light";
  plugins?: CanvasPlugin[];
};
```

## API

| Method | Description |
|---|---|
| `canvas.loadXML(xml)` | Load and render a BPMN XML string |
| `canvas.getXML()` | Return the currently loaded XML |
| `canvas.setTheme(theme)` | Switch between dark and light theme |
| `canvas.on(event, handler)` | Subscribe to canvas events |
| `canvas.off(event, handler)` | Unsubscribe a handler |
| `canvas.destroy()` | Clean up the canvas and remove from DOM |

## Events

```typescript
canvas.on("diagram:load", () => {
  console.log("Diagram loaded");
});

canvas.on("diagram:change", () => {
  console.log("Diagram modified");
});
```

## Plugins

The canvas accepts an array of plugins that can extend its behavior:

```typescript
import { BpmnCanvas } from "@bpmnkit/canvas";
import { createMinimapPlugin } from "@bpmnkit/canvas-plugin-minimap";
import { createZoomControlsPlugin } from "@bpmnkit/canvas-plugin-zoom-controls";

const canvas = new BpmnCanvas({
  container: document.getElementById("canvas"),
  plugins: [
    createMinimapPlugin(),
    createZoomControlsPlugin(),
  ],
});
```

### Plugin interface

```typescript
type CanvasPlugin = {
  name: string;
  install(api: CanvasApi): void;
  uninstall?(): void;
};
```

### Available plugins

| Package | Description |
|---|---|
| `@bpmnkit/canvas-plugin-minimap` | Overview minimap |
| `@bpmnkit/canvas-plugin-zoom-controls` | Zoom in/out buttons |
| `@bpmnkit/canvas-plugin-command-palette` | Keyboard command palette |
| `@bpmnkit/canvas-plugin-storage` | File persistence (IndexedDB) |
| `@bpmnkit/canvas-plugin-tabs` | Multi-file tab bar |
| `@bpmnkit/canvas-plugin-process-runner` | In-browser simulation controls |
| `@bpmnkit/canvas-plugin-token-highlight` | Visual token tracking |
| `@bpmnkit/canvas-plugin-ai-bridge` | AI chat integration |

---

### @bpmnkit/plugins

Thirty-four composable plugins for the BPMN canvas and editor — minimap, linting, simulation, AI bridge, storage and more.

Source: https://bpmnkit.com/docs/packages/plugins

## Overview

`@bpmnkit/plugins` is the capability layer above `@bpmnkit/canvas` and `@bpmnkit/editor`. The
canvas draws a diagram and exposes a `CanvasApi`; a plugin is anything that takes that API and
adds something — an overlay, a panel, a keyboard mode, a side effect on save.

Every plugin ships behind **its own entry point**, so a viewer that wants a minimap and
nothing else pays for a minimap and nothing else:

```typescript
import { createMinimapPlugin } from "@bpmnkit/plugins/minimap";
```

There is deliberately **no root export**. `import … from "@bpmnkit/plugins"` does not resolve,
because a barrel would pull all thirty-four into every bundle that wanted one.

## Installation

```sh
npm install @bpmnkit/plugins @bpmnkit/canvas
```

## Using a plugin

Most plugins are a factory you call and hand to the canvas:

```typescript
import { BpmnCanvas } from "@bpmnkit/canvas";
import { createMinimapPlugin } from "@bpmnkit/plugins/minimap";
import { createZoomControlsPlugin } from "@bpmnkit/plugins/zoom-controls";

const canvas = new BpmnCanvas({
  container: document.getElementById("app")!,
  xml,
  plugins: [createMinimapPlugin(), createZoomControlsPlugin()],
});
```

Plugins compose: they are independent, order-insensitive unless they say otherwise, and each
one cleans up after itself when the canvas is destroyed.

## What is available

**Navigation and view**

| Entry point | Export | What it adds |
|---|---|---|
| `minimap` | `createMinimapPlugin` | Overview panel; click to pan |
| `zoom-controls` | `createZoomControlsPlugin` | Zoom in/out/fit buttons |
| `flow-navigation` | `createFlowNavigationPlugin` | Keyboard cursor that walks the sequence flows |
| `model-navigation` | `createModelNavigationPlugin` | Drill into sub-processes and call activities |
| `presentation` | `createPresentationPlugin` | Step through a process as slides |
| `story-view` | `createStoryViewPlugin` | The process as readable prose cards |
| `ascii-view` | `createAsciiViewPlugin` | The diagram as text, via `@bpmnkit/ascii` |
| `watermark` | `createWatermarkPlugin` | A mark over the canvas |

**Editing**

| Entry point | Export | What it adds |
|---|---|---|
| `config-panel` | `createConfigPanelPlugin` | Property panel shell |
| `config-panel-bpmn` | `createConfigPanelBpmnPlugin` | The BPMN property editors themselves |
| `command-palette` | `createCommandPalettePlugin` | ⌘K palette for a viewer |
| `command-palette-editor` | `createCommandPaletteEditorPlugin` | The editor's own commands |
| `main-menu` | `createMainMenuPlugin` | Menu bar |
| `tabs` | `createTabsPlugin`, `InMemoryFileResolver` | Multi-file tabs |
| `history` | `saveCheckpoint`, `listCheckpoints`, `createHistoryPanel` | Named checkpoints |
| `storage` | `createStoragePlugin` | Persistence, with a host-supplied backend |
| `storage-tabs-bridge` | `createStorageTabsBridge` | Wires those two together |
| `element-docs` | `createElementDocsPlugin` | Inline BPMN reference for the selected element |

**Correctness**

| Entry point | Export | What it adds |
|---|---|---|
| `lint` | `createLintPlugin` | Findings on the canvas |
| `optimize` | `createOptimizePlugin` | The `@bpmnkit/core` optimizer, on the diagram |
| `pattern-advisor` | `createPatternAdvisorPlugin` | Fifteen pattern rules, with fixes |
| `variable-flow` | `createVariableFlowPlugin` | Producers and consumers per variable |
| `diff` | `createBpmnDiff` | Visual diff of two models |

**Execution**

| Entry point | Export | What it adds |
|---|---|---|
| `process-runner` | `createProcessRunnerPlugin` | Simulate, step, chaos mode, scenario tests |
| `token-highlight` | `createTokenHighlightPlugin` | Token positions on the canvas |
| `live-mode` | `createLiveModePlugin` | Auto-deploy and live instance overlay |
| `deploy` | `createDeployPlugin` | Deploy to a cluster, guarded by the optimizer |

**DMN, forms and FEEL**

| Entry point | Export | What it adds |
|---|---|---|
| `dmn-viewer` | `DmnViewer`, `injectDmnViewerStyles` | Render a decision table |
| `dmn-editor` | `DmnEditor` | Edit one |
| `form-viewer` | `FormViewer`, `injectFormViewerStyles` | Render a Camunda Form |
| `form-editor` | `FormEditor` | Edit one |
| `feel-playground` | `createFeelPlaygroundPlugin`, `buildFeelPlaygroundPanel` | Evaluate FEEL against live variables |

**Integration**

| Entry point | Export | What it adds |
|---|---|---|
| `ai-bridge` | `createAiBridgePlugin` | Natural-language edits over the compact model |
| `connector-catalog` | `createConnectorCatalogPlugin` | Browse and apply `@bpmnkit/connectors` |

## Styles

Plugins that render their own UI export their CSS as a string and an injector — for example
`FORM_VIEWER_CSS` and `injectFormViewerStyles` from `form-viewer`. The injectors are
id-guarded, so calling one twice is free, and a host that would rather ship the CSS itself can
take the string instead.

Brand colours come from `@bpmnkit/ui` tokens with hex fallbacks, so a plugin looks right
standalone and themes correctly inside an app that sets them.

## Stability

`@bpmnkit/plugins` carries the [1.0 stability promise](/docs/getting-started/stability): the
entry points listed above, and the exports and option types they name, will not change shape
without a major version.

Two clarifications, because a plugin package is where the edges are:

- **Adding a plugin is a minor.** A new entry point breaks nobody.
- **Rendered DOM and class names are not API.** How a panel is laid out, which elements it
  builds, and the class names inside it are presentation. Style through the documented CSS
  custom properties rather than by reaching into the markup.

---

### @bpmnkit/editor

Full BPMN editor — canvas, properties panel, AI bridge, and storage.

Source: https://bpmnkit.com/docs/packages/editor

## Overview

`@bpmnkit/editor` bundles everything needed to embed a full-featured BPMN editor
into any web application:

- **Canvas** — SVG viewer with pan/zoom
- **Properties panel** — edit element properties inline
- **AI bridge** — chat panel connected to a local AI server
- **Storage** — auto-save to IndexedDB with project/file management
- **HUD** — toolbar with undo/redo, zoom, optimize, and AI buttons
- **Side dock** — collapsible right panel (properties + AI tabs)

## Installation

```sh
pnpm add @bpmnkit/editor
```

## Basic Setup

```typescript
import { BpmnEditor, initEditorHud } from "@bpmnkit/editor";

// Create the editor
const editor = new BpmnEditor({
  container: document.getElementById("editor"),
  theme: "dark",
  persistTheme: true,   // read/write "bpmn-theme" in localStorage
});

// Initialize the HUD (toolbar overlay)
const hud = initEditorHud(editor);

// Load a diagram
await editor.loadXML(bpmnXml);
```

## With Side Dock

The side dock provides a collapsible properties + AI panel:

```typescript
import { BpmnEditor, initEditorHud, createSideDock } from "@bpmnkit/editor";

const editor = new BpmnEditor({
  container: document.getElementById("editor"),
});

const dock = createSideDock();
document.body.appendChild(dock.el);

const hud = initEditorHud(editor, {
  aiButton: dock.aiPane.button,
});
```

## HUD Options

```typescript
type HudOptions = {
  optimizeButton?: HTMLElement;   // inject an external "Optimize" button
  aiButton?: HTMLElement;         // inject an external "AI" button
};
```

## EditorOptions

```typescript
type EditorOptions = {
  container: HTMLElement;
  theme?: "dark" | "light";
  persistTheme?: boolean;         // auto-save theme to localStorage
  plugins?: CanvasPlugin[];
};
```

## SideDock API

```typescript
type SideDock = {
  el: HTMLElement;
  propertiesPane: HTMLElement;
  aiPane: { button: HTMLElement; el: HTMLElement };
  switchTab(tab: "properties" | "ai"): void;
  expand(): void;
  collapse(): void;
  collapsed: boolean;
  showPanel(): void;
  hidePanel(): void;
  setDiagramInfo(processName: string, fileName: string): void;
};
```

## Applying a change script

`applyProcessDelta` applies a change script (`parseProcessDelta` from `@bpmnkit/core`) to a
diagram someone drew, without laying it out again. It goes through the same modelling functions
a person's edit does, so only what the change touches moves:

- a new node is placed beside the node it follows, below anything in its way;
- new nodes written between two connected nodes (`a > new > b`) replace the flow `a > b`, keep
  its condition or default, and sit in the gap — the shapes right of it move along if the gap is
  too narrow, and pools and lanes widen with them;
- a new node joins the lane it is drawn in;
- removing a node with one way in and one way out joins its neighbours, unless the script
  connected them itself;
- a retyped node keeps its centre, extensions and flows.

```typescript
import { parseProcessDelta, writeProcessText } from "@bpmnkit/core";
import { applyProcessDelta } from "@bpmnkit/editor/headless";

const { text, aliases } = writeProcessText(defs);
const result = applyProcessDelta(defs, parseProcessDelta(modelOutput), { aliases });
// result.definitions, created, changed, removed, addressed, fixes, problems
```

It never throws on the script and never mutates `defs`. Ids that name nothing, kinds that
cannot be created and attributes the Zeebe schema forbids are reported in `problems` and left
out. Like the editor's other modelling functions, it acts on the first process. Pass
`ids: createIdFactory(seed)` for a result that replays identically.

A script's `with` lines configure connectors, on existing nodes or ones the script adds. They
need the connector catalog, which this package does not carry. Pass `applyConnectorLines` from
`@bpmnkit/core/connectors` as `applyConnectors`. Required inputs the lines left out come back as
`result.questions`.

```typescript
import { applyConnectorLines, connectorLineFor } from "@bpmnkit/core/connectors";

const { text, aliases } = writeProcessText(defs, { connectorLine: connectorLineFor });
const result = applyProcessDelta(defs, parseProcessDelta(modelOutput), {
  aliases,
  applyConnectors: applyConnectorLines,
});
```

## Full Editor with All Plugins

The landing page editor uses the `createStorageTabsBridge` plugin which wires together
tabs, storage, AI, and command palette in one call:

```typescript
import { createStorageTabsBridge } from "@bpmnkit/canvas-plugin-storage-tabs-bridge";
import { BpmnEditor, initEditorHud, createSideDock } from "@bpmnkit/editor";

const editor = new BpmnEditor({ container });
const dock = createSideDock();

const bridge = createStorageTabsBridge({
  mainMenu: menuPlugin,
  resolver: fileResolver,
  enableFileImport: true,
  getExamples: (tabsApi) => [
    {
      label: "Approval Flow",
      load: () => tabsApi.openTab({ xml: approvalFlowXml }),
    },
  ],
});

document.body.appendChild(dock.el);
const hud = initEditorHud(editor, { aiButton: dock.aiPane.button });
```

## Internationalisation

The editor and its first-party panels ship in ten languages. English is built in; the
other nine are separate entry points, so a bundle carries only the languages it imports.

| Language | Import |
|---|---|
| German | `@bpmnkit/editor/locales/de` |
| Spanish | `@bpmnkit/editor/locales/es` |
| French | `@bpmnkit/editor/locales/fr` |
| Italian | `@bpmnkit/editor/locales/it` |
| Dutch | `@bpmnkit/editor/locales/nl` |
| Polish | `@bpmnkit/editor/locales/pl` |
| Portuguese (Brazil) | `@bpmnkit/editor/locales/pt-BR` |
| Japanese | `@bpmnkit/editor/locales/ja` |
| Chinese (Simplified) | `@bpmnkit/editor/locales/zh-CN` |

`createTranslate(locale)` turns a locale into the `translate` hook. Pass the same hook to
the editor, the side dock and every plugin you mount:

```typescript
import { BpmnEditor, createSideDock, createTranslate, initEditorHud } from "@bpmnkit/editor";
import { de } from "@bpmnkit/editor/locales/de";
import { createConfigPanelPlugin } from "@bpmnkit/plugins/config-panel";
import { createConfigPanelBpmnPlugin } from "@bpmnkit/plugins/config-panel-bpmn";

const translate = createTranslate(de);
const dock = createSideDock({ translate });
const configPanel = createConfigPanelPlugin({ getDefinitions, applyChange, translate });
const configPanelBpmn = createConfigPanelBpmnPlugin(configPanel, { translate });
const editor = new BpmnEditor({ container, translate, plugins: [configPanel, configPanelBpmn] });
initEditorHud(editor); // the HUD reads the editor's hook
```

These plugins take a `translate` option: `config-panel`, `config-panel-bpmn`,
`command-palette`, `command-palette-editor` (third argument), `main-menu`, `history`,
`process-runner`, `tabs` and `storage-tabs-bridge`. The properties panel translates schema
labels, hints, placeholders and option labels when it draws them, so strings from a
connector template you add pass through unchanged.

**Pick the language at runtime.** `AVAILABLE_LOCALES` lists every language with its own
name, and `matchLocale(navigator.languages, codes)` picks the best match for the browser.
Load the chosen locale with a dynamic `import()`, so each language is its own chunk.
The strings are fixed when the UI is built — to switch language, rebuild the editor or
reload the page. The main menu has a ready-made Language section:

```typescript
createMainMenuPlugin({
  translate,
  language: {
    current: "de",
    options: AVAILABLE_LOCALES,
    onSelect(code) {
      localStorage.setItem("editor-locale", code);
      location.reload();
    },
  },
});
```

Set `lang` on the page (or on the editor's container) to the locale's code. Screen readers
use it, and Japanese and Chinese use it to choose the correct form of shared Han characters.
The `--bpmnkit-ds-font-*` tokens in `@bpmnkit/ui` add CJK fallback fonts under `:lang(ja)`
and `:lang(zh)`.

**Keys and plurals.** A key is the English text the UI asks for, such as `"Undo (Ctrl+Z)"` or
`"{count} elements selected"`. A key that a locale does not have falls back to English.
Placeholders in braces must stay the same in every translation. A message can also be a
plural object — `createTranslate` selects its form with `Intl.PluralRules` from `count`:

```typescript
const pl: Locale = {
  code: "pl",
  name: "Polski",
  messages: {
    "{count} elements selected": {
      one: "Zaznaczono {count} element",
      few: "Zaznaczono {count} elementy",
      many: "Zaznaczono {count} elementów",
      other: "Zaznaczono {count} elementu",
    },
  },
};
```

**Your own translation.** A `Translate` is only a function, so you can wrap a shipped
locale to override some strings, or supply a language that is not shipped:

```typescript
const base = createTranslate(de);
const translate: Translate = (key, vars) =>
  key === "Deploy" ? "Deployen" : base(key, vars);
```

The shipped translations are machine-assisted and checked against the BPMN terminology
that Camunda Modeler uses. Corrections are welcome — see "Improving a translation" in
`CONTRIBUTING.md`.

---

### @bpmnkit/feel

The FEEL expression language — lexer, parser, evaluator, formatter and syntax highlighter, with no dependencies.

Source: https://bpmnkit.com/docs/packages/feel

## Overview

`@bpmnkit/feel` implements FEEL (Friendly Enough Expression Language), the expression language
DMN decision tables and Camunda 8 condition expressions are written in. It passes 1,941 of the
2,053 FEEL cases in the [DMN TCK](https://dmn-tck.github.io/tck/) (94.5%), and matches 375 of
the 378 runnable examples in Camunda 8's FEEL documentation (see
[Camunda parity](#camunda-parity)). The cases it does not pass are listed, each with its
reason, in `packages/feel/tests/tck.test.ts` and `packages/feel/tests/camunda-parity.test.ts`,
and [Conformance](/docs/getting-started/conformance) has the full picture.

It is four things behind one entry point: a **lexer**, a recursive-descent **parser**, an AST
**evaluator** with 101 built-in functions, and a **formatter** and **syntax highlighter** for
editors. It has no dependencies and runs unchanged in Node.js and the browser.

Everything else in BPMN Kit that has to understand an expression uses it — gateway conditions
in `@bpmnkit/core`'s optimizer, the simulator in `@bpmnkit/engine`, the FEEL playground plugin,
and DMN evaluation.

## Installation

```sh
npm install @bpmnkit/feel
```

## Parsing and evaluating

Parsing and evaluation are separate steps, so you can parse once and evaluate many times, and
so a syntax error is a value rather than an exception.

```typescript
import { parseExpression, evaluate } from "@bpmnkit/feel";

const parsed = parseExpression("amount * 1.2 + fee");

if (parsed.errors.length === 0) {
  const result = evaluate(parsed.ast!, { vars: { amount: 100, fee: 5 } });
  console.log(result); // 125
}
```

`evaluate` takes an **`EvalContext`**, not a bare object — variables live under `vars`:

```typescript
interface EvalContext {
  /** The variables the expression may reference. */
  vars: Record<string, FeelValue>;
  /** Enclosing scope, searched when `vars` has no match. */
  parent?: EvalContext;
  /** The value `?` refers to, used by unary tests. */
  input?: FeelValue;
}
```

Parse errors carry their position, so an editor can underline them:

```typescript
parseExpression("1 +").errors;
// [{ message: "Expected expression after '+'", start: 3, end: 4 }]
```

## Unary tests

A DMN input entry is not an expression but a **unary test** — `> 5`, `"gold","silver"`,
`[1..10]` — evaluated against an input value. They have their own parse and evaluate pair.

```typescript
import { parseUnaryTests, evaluateUnaryTests } from "@bpmnkit/feel";

const test = parseUnaryTests('"gold","silver"');

evaluateUnaryTests(test.ast!, "gold", { vars: {} });   // true
evaluateUnaryTests(test.ast!, "bronze", { vars: {} }); // false
```

## What the language covers

```typescript
const run = (src: string, vars = {}) =>
  evaluate(parseExpression(src).ast!, { vars });

run('upper case("abc")');            // "ABC"
run('contains("foobar", "oo")');     // true
run("sum([1, 2, 3])");               // 6
run("[1, 2, 3, 4][item > 2]");       // [3, 4]  — list filter
run("{ a: 1, b: { c: 2 } }.b.c");    // 2       — context literal and path
run("[1..10]");                      // a range value
run('string length("héllo")');       // 5       — code points, not bytes
```

- **Temporal types** — `date`, `time`, `date and time`, `duration` and
  `years and months duration`, as structured values rather than strings:

  ```typescript
  run('date and time("2026-01-01T10:00:00")');
  // { type: "date-time", date: { type: "date", year: 2026, month: 1, day: 1 },
  //   time: { type: "time", hour: 10, minute: 0, second: 0 } }
  ```

- **Ranges** — `[1..10]`, `(0..1)`, and the fourteen DMN range functions that compare them
  (`before`, `after`, `meets`, `met by`, `overlaps`, `during`, `includes`, `coincides`, …).
- **101 built-in functions** across strings, numbers, lists, contexts and temporals, including
  Camunda's extensions to DMN (below).
- **Context literals and paths**, including nested access and filters.

## Camunda parity

Camunda 8 evaluates FEEL with its own engine, which adds functions and behaviour that DMN does
not define. This package implements them, so an expression written for Zeebe evaluates the
same way here:

| Area | Camunda extensions |
|---|---|
| Boolean | `get or else`, `assert` |
| Context | `context put` with a key path, `context merge`, `get value` with a key path |
| String | `string join`, `is blank`, `trim`, `extract`, `uuid`, `to base64`, `from base64` |
| List | `is empty`, `partition`, `duplicate values` |
| Conversion | `to json`, `from json`, `date and time(value, timezone)` |
| Temporal | `last day of month` (a date), `week of year`, time ± duration, duration ÷ duration |
| AI agent | `fromAi`, which returns its value unchanged |

```typescript
run('partition([1,2,3,4,5], 2)');                    // [[1,2], [3,4], [5]]
run('context put({x: 1}, ["y", "z"], 2)');           // { x: 1, y: { z: 2 } }
run('to json({a: 1, b: [true, null]})');             // '{"a":1,"b":[true,null]}'
run('date and time(@"2020-07-31T14:27:30@Europe/Berlin", "America/Los_Angeles")');
// the value of date and time("2020-07-31T05:27:30@America/Los_Angeles")
```

**Measured against Camunda's documentation.** `packages/feel/tests/camunda-parity.test.ts`
takes every worked example in the FEEL pages of Camunda's docs (`expression` then
`// result`), evaluates both sides, and compares them. The examples are read at test time from
`@bpmnkit/camunda-docspack`; `node packages/feel/tasks/extract-camunda-examples.mjs --skipped`
lists the ones that cannot run standalone and why (function signatures, prose results, `now()`
and other clock-dependent examples). Of the **378 runnable examples, 375 match**. The three
that do not:

- `round up(5.5)` and `round up(-5.5)` — the documented signature is `round up(n, scale)`, as
  in DMN, and these examples leave the scale out. This package holds to the signature.
- `date and time(@"2020-07-31T14:27:30", "Z")` — a date and time without a zone names no
  instant. Camunda reads it on the engine's own clock, so the documented result holds only
  where that clock is two hours ahead of UTC. This package returns `null`.

One difference is in how errors surface, not in which expressions are errors. Camunda fails
the evaluation: `assert(x, x > 0)` with `x = -1` stops with an error. This package follows DMN
and returns `null` for an evaluation error.

## Formatting and highlighting

`formatFeel` pretty-prints — note that it takes a **parsed node**, not source text:

```typescript
import { parseExpression, formatFeel } from "@bpmnkit/feel";

formatFeel(parseExpression("if  x>10 then  1 else 2").ast!);
```

`annotate` classifies source into typed tokens, which is what an editor wants:

```typescript
import { annotate } from "@bpmnkit/feel";

annotate("x > 1")[0];
// { kind: "variable", value: "x", start: 0, end: 1 }
```

`highlightToHtml` wraps those tokens in `<span class="feel-…">` elements for a ready-made
highlighter. `highlightFeel` is an alias for it, kept for compatibility.

## API Reference

| Export | Signature | Description |
|---|---|---|
| `parseExpression` | `(src: string) => ParseResult` | Parse an expression |
| `parseUnaryTests` | `(src: string) => ParseResult` | Parse a DMN input entry |
| `evaluate` | `(node, ctx: EvalContext) => FeelValue` | Evaluate a parsed expression |
| `evaluateUnaryTests` | `(node, input, ctx) => boolean` | Test an input against unary tests |
| `evaluateUnaryTest` | `(node, input, ctx) => boolean` | A single unary test |
| `tokenize` | `(src: string) => FeelToken[]` | Raw token stream |
| `formatFeel` | `(node, opts?) => string` | Pretty-print a **parsed node** |
| `annotate` | `(src: string) => AnnotatedToken[]` | Tokens classified for highlighting |
| `highlightToHtml` | `(src: string) => string` | Tokens wrapped in `<span>` elements |
| `highlightFeel` | `(src: string) => string` | Alias for `highlightToHtml` |

### `ParseResult`

```typescript
interface ParseResult {
  ast: FeelNode | null;
  errors: ParseError[]; // { message, start, end }
}
```

### Types and guards

`FeelValue` is the union every evaluation produces. The structured members —
`FeelDate`, `FeelTime`, `FeelDateTime`, `FeelDayTimeDuration`,
`FeelYearsMonthsDuration`, `FeelRange`, `FeelContext`, `FeelFunction` — each come with a
type guard (`isFeelDate`, `isFeelRange`, …), plus `getProperty` for path access. Import them
by name from the package root.

## Stability

`@bpmnkit/feel` carries the [1.0 stability promise](/docs/getting-started/stability): its
exports will not change shape without a major version.

---

### @bpmnkit/worker-client

Thin Zeebe REST client for standalone workers — no BPMNKit SDK required at runtime.

Source: https://bpmnkit.com/docs/packages/worker-client

`@bpmnkit/worker-client` is a thin TypeScript wrapper around the Zeebe REST API. It is the
only runtime dependency for scaffolded BPMNKit workers. It works with both local reebe and
Camunda 8 cloud.

## Installation

```sh
npm install @bpmnkit/worker-client
```

## Quick start

```typescript
import { createWorkerClient } from "@bpmnkit/worker-client"

const client = createWorkerClient()

for await (const job of client.poll("com.example:send-email:1")) {
  try {
    await sendEmail(job.variables)
    await job.complete({ sent: true })
  } catch (err) {
    await job.fail(err instanceof Error ? err.message : String(err))
  }
}
```

## `createWorkerClient(options?)`

Factory function. Reads connection details from environment variables by default.

```typescript
const client = createWorkerClient({
  address:      "http://localhost:26500",  // or ZEEBE_ADDRESS
  clientId:     "...",                     // or ZEEBE_CLIENT_ID
  clientSecret: "...",                     // or ZEEBE_CLIENT_SECRET
  tokenUrl:     "...",                     // or ZEEBE_TOKEN_URL
  audience:     "zeebe.camunda.io",        // or ZEEBE_TOKEN_AUDIENCE
  workerName:   "my-worker",              // sent during job activation
})
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `address` | `string` | `ZEEBE_ADDRESS` or `http://localhost:26500` | Zeebe REST base URL |
| `clientId` | `string` | `ZEEBE_CLIENT_ID` | OAuth2 client ID (Camunda SaaS) |
| `clientSecret` | `string` | `ZEEBE_CLIENT_SECRET` | OAuth2 client secret (Camunda SaaS) |
| `tokenUrl` | `string` | `ZEEBE_TOKEN_URL` or Camunda SaaS endpoint | OAuth2 token URL |
| `audience` | `string` | `ZEEBE_TOKEN_AUDIENCE` or `zeebe.camunda.io` | OAuth2 audience |
| `workerName` | `string` | `"bpmnkit-worker"` | Worker name sent during activation |

### Returns

A `WorkerClient` object with a single `poll()` method.

## `client.poll(jobType, options?)`

Async generator. Continuously polls Zeebe for jobs of the given type. Each activation request
long-polls: the engine holds it open for up to `requestTimeout` until a job is available. When
a poll comes back empty, the next one starts at least 5 seconds after it began.

Transient failures — a network error, `408`, `429`, a `5xx`, or a token endpoint that is down —
are passed to `onError` and retried. Anything retrying cannot fix, such as credentials the
token endpoint rejects or a `401`/`403`/`400` from the engine, ends the loop: the generator
throws, so a worker with a wrong secret stops with a message instead of idling forever.

```typescript
for await (const job of client.poll("my-job-type", { maxJobs: 10, timeout: 60_000 })) {
  // handle job
}
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `maxJobs` | `number` | `5` | Maximum jobs to activate per poll request |
| `timeout` | `number` | `300_000` | Activation lock timeout in milliseconds |
| `requestTimeout` | `number` | `20_000` | How long the engine may hold an activation request open (long polling), in ms; `0` uses the engine default |
| `onError` | `(error: Error) => void` | warning on stderr | Called with each transient error before the poll is retried |
| `signal` | `AbortSignal` | — | Stops the poll: the generator returns once it aborts, even mid-request or mid-pause |

### Yields `ActivatedJob`

Each iteration yields a job with these fields and methods:

```typescript
interface ActivatedJob {
  key: string                            // unique job key
  jobType: string                        // job type from BPMN task definition
  processInstanceKey: string
  bpmnProcessId: string
  elementId: string
  retries: number                        // remaining retries — use to pass to fail()
  variables: Record<string, unknown>     // process variables from the instance

  complete(variables?: Record<string, unknown>): Promise<void>
  fail(message: string, retries?: number): Promise<void>
  throwError(errorCode: string, message: string, variables?: Record<string, unknown>): Promise<void>
}
```

## `job.complete(variables?)`

Completes the job, optionally returning output variables to the process instance.

```typescript
await job.complete({ approved: true, reviewedAt: new Date().toISOString() })
```

## `job.fail(message, retries?)`

Marks the job as failed. `retries` is how many retries the job has left afterwards. It
defaults to `job.retries - 1` (never below `0`), so Zeebe retries until the task's retries are
used up and then raises an incident. Pass `0` to raise the incident at once.

```typescript
await job.fail("External API returned 503")        // one retry fewer
await job.fail("Invalid customer record", 0)       // incident now: retrying will not help
```

## `job.throwError(errorCode, message, variables?)`

Throws a BPMN error that can be caught by an error boundary event on the task in the diagram.

```typescript
await job.throwError("PAYMENT_DECLINED", "Card declined by issuer", { code: "05" })
```

## When the engine refuses a call

`complete`, `fail` and `throwError` reject when the engine answers with an error status — for
example because the job has timed out and been handed to another worker, or was cancelled. The
error message names the job key, the status and the response body. Catch it where you settle
the job if your worker should keep going:

```typescript
try {
  await job.complete({ sent: true })
} catch (err) {
  console.error(err instanceof Error ? err.message : err)
}
```

Before this change these calls resolved even when the engine had refused them, so a lost
completion went unnoticed.

## OAuth2 (Camunda SaaS)

When `clientId` and `clientSecret` are present (either via options or env vars), the client
fetches an OAuth2 token before the first request and refreshes it automatically 60 seconds
before expiry. No manual token management required.

```sh
ZEEBE_ADDRESS=https://your-cluster.bru-2.zeebe.camunda.io:443
ZEEBE_CLIENT_ID=abc123
ZEEBE_CLIENT_SECRET=def456
node dist/index.js
```

## Environment variables

| Variable | Description |
|---|---|
| `ZEEBE_ADDRESS` | Zeebe REST base URL |
| `ZEEBE_CLIENT_ID` | OAuth2 client ID |
| `ZEEBE_CLIENT_SECRET` | OAuth2 client secret |
| `ZEEBE_TOKEN_URL` | OAuth2 token URL |
| `ZEEBE_TOKEN_AUDIENCE` | OAuth2 audience |

## See also

- [Standalone Workers](/docs/guides/workers-standalone) — scaffolding, running, and deploying workers
- [AI-Driven Implementation](/docs/guides/ai-implement) — generate workers automatically with `/implement`

---

### @bpmnkit/ascii

Render BPMN diagrams, DMN decision tables and Camunda Forms as Unicode text.

Source: https://bpmnkit.com/docs/packages/ascii

## Overview

`@bpmnkit/ascii` turns a diagram into text. It takes the XML and returns a string — no canvas,
no DOM, no headless browser — so a process can be shown somewhere a picture cannot go: a
terminal, a CI log, a pull-request comment, or a prompt.

That last one is the reason it exists. A model reading a diagram as a grid of labelled boxes
gets the topology in a few hundred tokens, which is a great deal cheaper than the XML and a
great deal more legible than a screenshot. `casen view` is this package with a file path in
front of it.

Three renderers, one per artifact kind, and no dependencies beyond `@bpmnkit/core`.

## Installation

```sh
npm install @bpmnkit/ascii
```

## Rendering a process

```typescript
import { renderBpmnAscii } from "@bpmnkit/ascii";
import { readFileSync } from "node:fs";

console.log(renderBpmnAscii(readFileSync("order.bpmn", "utf-8")));
```

```text
╭─────────╮           ┌──────────────────────┐          ╭─────────╮
│ ○ Start │──────────►│ [svc] Process Order  │─────────►│ ● End   │
╰─────────╯           └──────────────────────┘          ╰─────────╯
```

Shapes follow BPMN. Events are rounded boxes carrying a marker — `○` start, `●` end, `◎`
intermediate catch, `◉` throw, `◈` boundary. Activities are square boxes with a three-letter
type tag — `[svc]`, `[usr]`, `[scr]`, `[snd]`, `[rcv]`, `[dmn]`, `[man]`, `[cal]`, `[sub]`,
`[txn]`. Gateways are diamonds — `×` exclusive, `+` parallel, `◇` inclusive, `?` event-based,
`✱` complex. Labels are truncated to the box, which keeps columns aligned on a wide process.

The layout comes from the diagram's own coordinates, so what you get is the shape someone drew
rather than a re-layout. A model with no diagram interchange has nothing to place — run
`applyAutoLayout` from `@bpmnkit/core` first if you built it in code.

## Rendering a decision table

```typescript
import { renderDmnAscii } from "@bpmnkit/ascii";

console.log(renderDmnAscii(readFileSync("risk-score.dmn", "utf-8")));
```

```text
DRD
───

Risk score [FIRST]
──────────────────

╔═══╦═════════╦════════════╦════════╗
║ F ║ Amount  ║ Country    ║ Risk   ║
╠═══╬═════════╬════════════╬════════╣
║ 1 ║ < 1000  ║ "DE", "AT" ║ "low"  ║
║ 2 ║ >= 1000 ║            ║ "high" ║
╚═══╩═════════╩════════════╩════════╝
```

The hit policy is shown beside the table name and in the corner cell, because a table read
without it means something different — an empty cell under `FIRST` is "anything, and stop
here", which is not what it looks like.

## Rendering a form

```typescript
import { renderFormAscii } from "@bpmnkit/ascii";

console.log(renderFormAscii(readFileSync("approval.form", "utf-8")));
```

Fields are listed in layout order with their keys, types and validation, so a form can be
reviewed in the same place as the process that raises it.

## API Reference

| Export | Signature |
|---|---|
| `renderBpmnAscii` | `(xml: string, options?: RenderOptions) => string` |
| `renderDmnAscii` | `(xml: string, options?: RenderOptions) => string` |
| `renderFormAscii` | `(json: string, options?: RenderOptions) => string` |

Each takes the file's text and returns the rendering. Parsing is strict — a document that is
not valid BPMN throws, naming what it found — so wrap the call if you are rendering a
directory. A document that parses but holds no flow elements
renders as `(empty)`.

### `RenderOptions`

```typescript
interface RenderOptions {
  /**
   * Heading shown above the diagram.
   * Defaults to the process name from the XML; pass `false` for no heading.
   */
  title?: string | false;
}
```

## From the command line

`casen view` wraps all three, picking the renderer from the file extension:

```sh
casen view order.bpmn
casen view risk-score.dmn
```

See [`casen view`](/docs/cli/view) for the flags it adds on top.

## Stability

`@bpmnkit/ascii` carries the [1.0 stability promise](/docs/getting-started/stability): its
exports will not change shape without a major version.

The promise covers the three function signatures and `RenderOptions`. It does **not** cover
the exact characters that come out — box-drawing details, column widths and truncation are
presentation, and improving them is a minor. Do not assert on the rendering byte for byte.

---

### @bpmnkit/connector-gen

Generate Camunda REST connector element templates from OpenAPI 3.x and Swagger 2.x specs.

Source: https://bpmnkit.com/docs/packages/connector-gen

## Overview

`@bpmnkit/connector-gen` parses OpenAPI 3.x and Swagger 2.x specifications and generates Camunda
REST connector element templates — the `.json` files imported into Camunda Modeler to pre-configure
`bpmn:ServiceTask` nodes.

- **OpenAPI 3.x and Swagger 2.x** — JSON and YAML
- **One template per operation** — method, URL, params, body, auth, output, retries all wired up
- **100-entry built-in catalog** — GitHub, Stripe, Slack, Xero, DocuSign, Adyen, and more
- **Auth auto-detection** — reads `components.securitySchemes` and pre-selects the right auth block
- **FEEL expressions** — path parameters become `="https://base/"+param` expressions automatically
- **Body expansion** — optionally decompose request body properties into individual typed fields
- Zero dependencies beyond `yaml` for YAML parsing

## Installation

```sh
pnpm add @bpmnkit/connector-gen
```

## Quick start

```typescript
import { generate, writeTemplates } from "@bpmnkit/connector-gen"
import { readFileSync } from "node:fs"

const spec = readFileSync("openapi.yaml", "utf8")

const templates = generate(spec, {
  idPrefix: "com.myorg",
})

await writeTemplates(templates, { outputDir: "./templates" })
// Writes one .json file per operation into ./templates/
```

## Generating from a URL

```typescript
import { generateFromUrl } from "@bpmnkit/connector-gen"

const { templates, files } = await generateFromUrl(
  "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
  {
    idPrefix: "com.myorg",
    outputDir: "./templates",
  }
)

console.log(`Wrote ${files.length} templates`)
```

## Generating from the catalog

The built-in catalog provides spec URLs and auth defaults for 100 popular APIs:

```typescript
import { generateFromCatalog } from "@bpmnkit/connector-gen"

// Use catalog defaults
const { templates, files, entry } = await generateFromCatalog("stripe", {
  outputDir: "./templates",
})

// Override catalog defaults
await generateFromCatalog("github", {
  outputDir: "./templates",
  idPrefix: "com.myorg",
  defaultAuthType: "bearer",
  filter: "issues|pulls",
  expandBody: true,
})
```

## `GeneratorOptions`

| Option | Type | Description |
|---|---|---|
| `idPrefix` | `string` | Reverse-DNS prefix for template IDs, e.g. `"io.mycompany"` |
| `defaultAuthType` | `AuthHint` | Pre-select auth type; auto-detected from spec if omitted |
| `baseUrl` | `string` | Override the base URL from `servers[0].url` in the spec |
| `expandBody` | `boolean` | Decompose top-level body properties into individual typed fields |
| `filter` | `string` | Regex applied to `operationId` and `summary` to filter operations |

```typescript
type AuthHint =
  | "noAuth"
  | "apiKey"
  | "basic"
  | "bearer"
  | "oauth-client-credentials-flow"
```

## `WriteOptions`

| Option | Type | Description |
|---|---|---|
| `outputDir` | `string` | Directory to write `.json` files into |
| `format` | `"one-per-op" \| "array"` | One file per operation (default) or all in one array file |

## Auth blocks

Every generated template includes a full 5-type auth block with visibility conditions, so users can
switch auth method in Camunda Modeler without editing the file.

| `AuthHint` | Fields in the template |
|---|---|
| `noAuth` | No auth fields shown |
| `apiKey` | `API Key` String field (sent as a header) |
| `basic` | `Username` + `Password` fields (HTTP Basic) |
| `bearer` | `Bearer Token` String field |
| `oauth-client-credentials-flow` | `Client ID`, `Client Secret`, `Token URL`, `Scopes` |

Auth is auto-detected from `components.securitySchemes`. The detected or specified type is
pre-selected in the template dropdown.

## Body expansion

By default the request body is a single FEEL `Text` field accepting a JSON expression. With
`expandBody: true`, top-level properties of the request body schema become individual typed input
fields — `String`, `Number`, or `Boolean`:

```typescript
// Default: one body field
generate(spec, { idPrefix: "com.myorg" })
// → body: Text (FEEL expression)

// Expanded: one field per top-level body property
generate(spec, { idPrefix: "com.myorg", expandBody: true })
// → to: String, subject: String, html: String, ...
```

## Lower-level API

All internals are exported if you need fine-grained control:

```typescript
import {
  parseOpenApi,       // parse YAML or JSON string → OpenApiDoc
  getOperations,      // enumerate all operations with resolved params and schemas
  detectDefaultAuth,  // infer AuthHint from components.securitySchemes
  buildTemplate,      // build one ConnectorTemplate from one OperationWithMeta
  buildTemplates,     // build all templates from all operations
  writeTemplates,     // write ConnectorTemplate[] to disk
} from "@bpmnkit/connector-gen"

const doc = parseOpenApi(specText)
const auth = detectDefaultAuth(doc)           // "bearer" | "apiKey" | ...
const ops = getOperations(doc, "createUser")  // filter regex optional

const templates = buildTemplates(ops, {
  idPrefix: "com.myorg",
  defaultAuthType: auth,
})

await writeTemplates(templates, {
  outputDir: "./out",
  format: "array",  // all in one file
})
```

## API index

`@bpmnkit/connector-gen/api-index` is an offline index of the catalog's HTTP APIs. It is built
from their OpenAPI specs, so nothing is fetched at runtime. It holds about 80 services and
20,000 operations. For each service it keeps the base URL and how it authenticates. For each
operation it keeps:

- the method and path;
- a summary of twelve words at most;
- the query parameters, top-level body fields and required headers, required ones marked `*`.

Each service is its own module, so loading Stripe evaluates only Stripe:

```typescript
import { API_SERVICES, loadApiService } from "@bpmnkit/connector-gen/api-index"

API_SERVICES.map((s) => s.id)            // ["github", "cloudflare", "stripe", "notion", …]
const stripe = await loadApiService("stripe")
stripe?.baseUrl                          // "https://api.stripe.com"
stripe?.operations.find((o) => o.path === "/v1/customers" && o.method === "POST")
// { method: "POST", path: "/v1/customers", summary: "Create a customer",
//   body: ["name", "email", "description", …], form: true }
```

[`@bpmnkit/core/connectors`](/docs/packages/connectors#api-cards) turns these into **API
cards** for a model, and completes REST connector calls from them. `casen connector api
"create a stripe customer"` prints the cards.

- **Building.** `pnpm update-api-index` (`scripts/build-api-index.mjs`) fetches each catalog
  spec once. It reads OpenAPI 3 and Swagger 2.
  - The weekly connector-templates workflow runs it and opens a pull request when something
    changed.
  - A spec that cannot be fetched keeps its previous entry.
- **Base URLs.** A spec whose host stands for a tenant's own, like Jira's
  `your-domain.atlassian.net`, has no `baseUrl`; the call needs the full URL.
- **Licenses.** Only specs under a permissive license, or none stated, are indexed. A spec
  that names a non-commercial, copyleft or proprietary license is left out.

## Catalog reference

Use `CATALOG` and `getCatalogEntry` to inspect or extend the catalog programmatically:

```typescript
import { CATALOG, getCatalogEntry } from "@bpmnkit/connector-gen"

// List all entries
for (const entry of CATALOG) {
  console.log(entry.id, entry.name, entry.defaultAuth)
}

// Look up one entry
const stripe = getCatalogEntry("stripe")
// → { id: "stripe", name: "Stripe API", url: "...", idPrefix: "io.stripe", defaultAuth: "basic" }
```

### Built-in entries

| ID | Name | Default auth |
|---|---|---|
| `github` | GitHub REST API | bearer |
| `cloudflare` | Cloudflare API | bearer |
| `stripe` | Stripe API | basic |
| `notion` | Notion API | bearer |
| `resend` | Resend Email API | bearer |
| `openai` | OpenAI API | bearer |
| `figma` | Figma API | bearer |
| `twilio` | Twilio Messaging API | basic |
| `slack` | Slack Web API | bearer |
| `jira` | Atlassian Jira API | bearer |
| `hubspot` | HubSpot CRM API | oauth-client-credentials-flow |
| `discord` | Discord API | bearer |
| `pagerduty` | PagerDuty API | apiKey |
| `zoom` | Zoom API | oauth-client-credentials-flow |
| `mailchimp` | Mailchimp API | apiKey |
| `asana` | Asana API | bearer |
| `sendgrid` | SendGrid Mail API | bearer |
| `paypal` | PayPal Payments API | oauth-client-credentials-flow |
| `plaid` | Plaid API | apiKey |
| `vercel` | Vercel API | bearer |
| `anthropic` | Anthropic API | apiKey |
| `shopify` | Shopify Admin API | bearer |
| `datadog` | Datadog API | apiKey |
| `sentry` | Sentry API | bearer |
| `intercom` | Intercom API | bearer |
| `contentful` | Contentful Management API | bearer |
| `airtable` | Airtable API | bearer |
| `twitch` | Twitch Helix API | oauth-client-credentials-flow |
| `klaviyo` | Klaviyo API | apiKey |
| `brex` | Brex API | oauth-client-credentials-flow |

## `CatalogEntry` type

```typescript
interface CatalogEntry {
  id: string
  name: string
  description: string
  url: string           // OpenAPI spec download URL
  idPrefix: string      // suggested reverse-DNS prefix
  defaultAuth: AuthHint
}
```

## CLI

The same functionality is available via `casen connector generate` and `casen connector catalog`.
See the [CLI reference](/docs/cli/connector).

---

### @bpmnkit/flow

Code-first durable flows — one TypeScript definition yields the BPMN, the job types, the message correlation and the worker.

Source: https://bpmnkit.com/docs/packages/flow

`@bpmnkit/flow` lets you write a durable workflow as a chain of TypeScript steps. From that
one definition it derives the executable BPMN process, a job type for every step, the message
correlation of every wait, and a worker that serves the handler steps. The model and the code
cannot drift apart, because there is only one of them.

The engine holds the run state, not your process. An instance survives a crash or a reboot and
continues at the step it reached. That makes a flow a good home for agent work: an LLM decides
what to do, and the engine remembers what is done. See
[Durable Agent Flows](/docs/guides/durable-agent-flows) for the end-to-end guide.

The package is [Experimental](/docs/getting-started/stability#product-tiers).

## Installation

```sh
npm install @bpmnkit/flow
```

## Quick start

```typescript
import { writeFileSync } from "node:fs"
import { defineFlow } from "@bpmnkit/flow"

const review = defineFlow("pr-review", { name: "PR review" })
  .input<{ prKey: string }>()
  .run("fetch-diff", async ({ prKey }) => ({ diff: await gh.diff(prKey) }))
  .agent("review", { role: "pr-review", prompt: "Review this diff:\n{{diff}}", result: "verdict" })
  .waitFor("ci-green", { correlationKey: "prKey" })
  .approve("approve-merge", { candidateGroups: "maintainers" })
  .run("merge", async ({ prKey, verdict }) => ({ merged: await gh.merge(prKey, verdict) }))
  .build()

writeFileSync("pr-review.bpmn", review.toXml()) // deploy with `casen deploy deploy pr-review.bpmn`
const worker = review.worker() // serves fetch-diff and merge
```

## Steps

`defineFlow(id, { name? })` starts a flow. Chain steps, then call `build()`. Every method
returns a new builder, so a builder you keep a reference to never changes.

| Method | BPMN element | Adds to the variables |
|---|---|---|
| `.input<I>()` | — | `I` |
| `.run(id, handler, { name?, retries? })` | service task, job type `<flowId>.<id>` | what the handler returns |
| `.agent(id, { role, rank?, prompt, result? })` | service task, job type `agent:<role>` or `agent:<rank>:<role>` | `{ [result]: string }` — default `result` |
| `.waitFor<P>(id, { correlationKey, message? })` | message catch event, correlated on `=<correlationKey>` | `P` |
| `.approve<P>(id, { name?, assignee?, candidateGroups? })` | Camunda user task | `P` |
| `.loop(id, body, { until, max, counter?, name?, escalate? })` | a bounded repeat — see [Loops](#loops) | what the body adds, and the counter |

Step ids must be unique in the whole flow, loop bodies included, and must not be `start` or
`end`, which the flow uses for its own events. `retries` defaults to 3. A wait's `message`
defaults to its id.

### Typed data flow

Each step's output joins the variables that later steps see. These are compile errors:

```typescript
defineFlow("t")
  .input<{ a: string }>()
  .run("one", (v) => ({ c: v.b }))                           // no variable `b`
  .agent("two", { role: "r", prompt: "Summarise {{b}}" })     // no variable `b` in the prompt
  .waitFor("three", { correlationKey: "b" })                  // no variable `b` to correlate on
```

A step that returns an existing variable name replaces its type for the steps after it.

### Handlers

A handler gets the instance's variables and a context, and returns the variables it adds, or
nothing:

```typescript
.run("charge", async ({ orderId, amount }, { jobKey }) => {
  await payments.charge(orderId, amount, { idempotencyKey: jobKey })
  return { charged: true }
})
```

Delivery is at least once. If the worker crashes after the handler finished but before the
engine heard about it, the handler runs again. Use `jobKey` (or a business key) to make the
side effect idempotent. A handler that throws fails the job; the engine retries it until the
step's retries run out and then raises an incident.

## Loops

`.loop()` repeats its body until a FEEL condition holds, at most `max` times. Agent work is
mostly loops — review, fix, review again until the reviewer approves — and a loop with a bound
cannot burn tokens forever:

```typescript
defineFlow("pr")
  .input<{ pr: string }>()
  .loop(
    "review-loop",
    (b) => b.agent("review", { role: "pr-review", prompt: "Review {{pr}}. Start with APPROVE or REJECT.", result: "verdict" }),
    {
      until: 'starts with(verdict, "APPROVE")',
      max: 3,
      between: (b) => b.agent("fix", { role: "feature", prompt: "Address this review of {{pr}}:\n{{verdict}}" }),
      escalate: { candidateGroups: "leads" },
    },
  )
  .run("merge", async ({ pr, round }) => ({ merged: await gh.merge(pr, `approved in round ${round}`) }))
  .build()
```

The body and `between` are builders of their own. The body sees the variables from before the
loop plus the counter; `between` also sees what the body added; the flow after the loop sees
what the body added. Each round:

1. runs the body,
2. adds 1 to the counter (`round` unless you name another; it is 0 when the loop starts),
3. ends the loop if `until` holds — otherwise, if `max` rounds are done, gives a person the
   `escalate` user task and ends the loop after it; otherwise runs `between` and another round.

So a PR approved on the first review is never "fixed", and after the third rejection the next
step is a person, not a fourth agent run.

| Option | Default | Description |
|---|---|---|
| `until` | — (required) | FEEL condition, with or without a leading `=`. It must evaluate to `true` or `false` |
| `max` | — (required) | Rounds before a person is asked. A whole number, at least 1 |
| `counter` | `"round"` | Variable counting the rounds done. A loop inside another needs its own |
| `name` | the id | Label on the loop's gateway |
| `between` | — | `(b) => b…` — steps run only when another round follows |
| `escalate` | — | `{ name?, assignee?, candidateGroups? }` for the user task at `max` |

In BPMN a loop is ordinary elements, so it opens in any modeler: a script task `<id>-start`
sets the counter to 0, the exclusive gateway `<id>` joins the first round and the repeats,
the body follows, the script task `<id>-next` counts the round, and the exclusive gateway
`<id>-check` leaves to `<id>-end` (done), to the user task `<id>-escalate` (gave up), or —
its default flow — through the `between` steps back to `<id>`. Those ids are taken, like step
ids.

## `Flow`

| Member | Description |
|---|---|
| `toXml()` | The laid-out BPMN XML to deploy |
| `definitions()` | The same process as a `BpmnDefinitions` object |
| `jobTypes` | Job types of the `.run()` steps |
| `agentJobTypes` | Job types the agent workforce must serve |
| `steps` | The steps, in order; a loop's steps are in its `body` |
| `runSteps` | Every `.run()` step, loop bodies included, with its `jobType` and `handler` |
| `worker(options?)` | Starts polling the `.run()` job types |

### `flow.worker(options?)`

Returns `{ done, stop() }` at once. `done` settles when every poll has ended: it resolves after
`stop()` and rejects with the first error polling cannot recover from, such as rejected
credentials. `stop()` resolves once the jobs in progress are settled.

| Option | Default | Description |
|---|---|---|
| `address`, `clientId`, … | environment | [`@bpmnkit/worker-client`](/docs/packages/worker-client) connection options |
| `maxJobs` | `1` | Jobs activated per poll. A step's jobs run one after another |
| `timeout` | `300_000` | Job lock timeout, in ms |
| `onError` | warning on stderr | Transient poll errors, and jobs the engine would not settle |
| `signal` | — | Stops the worker when it aborts |
| `client` | — | A `WorkerClient` to use instead of creating one |

## Testing a flow on the simulator

`definitions()` deploys straight into [`@bpmnkit/engine`](/docs/packages/engine), and
`runSteps` lists each handler step's job type and handler:

```typescript
import { Engine } from "@bpmnkit/engine"

const engine = new Engine()
engine.deploy({ bpmn: review.definitions() })
for (const step of review.runSteps) {
  engine.registerJobWorker(step.jobType, async (job) => {
    job.complete({ ...(await step.handler(job.variables, { jobKey: job.id, processInstanceKey: "1", retries: 3 })) })
  })
}
engine.registerJobWorker("agent:pr-review", (job) => job.complete({ verdict: "approve" }))
```

## The agent contract

An `.agent()` step is a service task with two task headers: `prompt` (the template) and
`resultVariable` (where the output goes). `casen agent work` serves it — see
[Durable Agent Flows](/docs/guides/durable-agent-flows). To write your own agent worker, use
the same helpers:

| Export | Description |
|---|---|
| `agentJobType(role, rank?)` | `agent:<role>`, or `agent:<rank>:<role>` |
| `agentJobTypes(roles, rank?)` | Every type a worker with these roles serves: each role, then each role at its rank |
| `renderPrompt(template, variables)` | Fills `{{name}}` — strings as is, anything else as JSON. Throws on a missing variable |
| `promptVariables(template)` | The variable names a template refers to |
| `AGENT_PROMPT_HEADER`, `AGENT_RESULT_HEADER`, `DEFAULT_AGENT_RESULT` | `"prompt"`, `"resultVariable"`, `"result"` |

---

### @bpmnkit/docspack

BPMN Kit documentation as an offline, version-locked package that AI agents can install and search.

Source: https://bpmnkit.com/docs/packages/docspack

## Overview

`@bpmnkit/docspack` ships the documentation you are reading as an npm package. An agent
installs it, asks a question, and gets back the two or three passages that answer it —
not a whole documentation site, and not whatever the model remembers about an older
release.

It follows the [docspack package format](https://docspack.dev/spec), so the upstream
`docspack` CLI indexes it like any other vendor pack. The bundled `bpmnkit-docs` command
does the same job with no extra tooling.

- **Offline** — `ask`, `search` and `list` read the filesystem only. No server, no network
  call, nothing resident between questions
- **Version-locked** — the installed `package.json` version wins over the manifest, so an
  agent reads the docs for the release the project actually has
- **Bounded** — three chunks and 3,000 tokens by default, budgeted from the manifest
  before any content is read
- **Real retrieval** — BM25 with Porter stemming, so `authenticate` finds a passage that
  only says `authentication`; tags and API identifiers weigh 3× prose
- Zero runtime dependencies

## The other pack

BPMN Kit publishes a second pack:
**[`@bpmnkit/camunda-docspack`](/docs/packages/camunda-docspack)**, the Camunda 8
documentation — BPMN and FEEL references, engine concepts, best practices and the
Orchestration Cluster API. `bpmnkit-docs` reads both, so ask this package how to
drive the library and that one what the engine does:

```sh
npx bpmnkit-docs ask "how should I name an exclusive gateway" --pack @bpmnkit/camunda-docspack
```

Install them together, and tell your agent about both — see
[Using BPMN Kit with AI](/docs/guides/using-bpmnkit-with-ai).

## Installation

```sh
pnpm add -D @bpmnkit/docspack @bpmnkit/camunda-docspack
```

## Giving an agent access

Any agent with a shell can run the command, so one paragraph in `AGENTS.md`, `CLAUDE.md`
or `.cursor/rules` is the whole setup:

```md
Run `npx bpmnkit-docs ask "<question>"` for BPMN Kit documentation, and
`npx bpmnkit-docs ask "<question>" --pack @bpmnkit/camunda-docspack` for Camunda 8
documentation — BPMN semantics, FEEL, engine behaviour, the REST API. Both answer
from the versions this project installed. Prefer what they return over recalled
knowledge — when the two disagree, the retrieved chunk is right.
```

## Asking a question

```sh
npx bpmnkit-docs ask "how do I deploy a process to Camunda 8"
```

```
## @bpmnkit/docspack@0.0.1/getting-started.quick-start.step-3-deploy-to-camunda-8

# Quick Start — Step 3: Deploy to Camunda 8

When you're ready for production, deploy to a real Camunda 8 cluster:
...

---
Source: /docs/getting-started/quick-start

---
cost: 1,204 tokens, capped at 3,000
```

Every answer names the package, the version and the chunk it came from, and closes with
what it cost. An agent can quote the chunk id back when a passage turns out to be wrong.

## Reading it yourself

`search` runs the same query and prints the ranking instead of the content:

```sh
npx bpmnkit-docs search "exclusive gateway condition"
```

```
5 result(s) for "exclusive gateway condition"

  14.73  @bpmnkit/docspack@0.0.1/guides.gateways.exclusive-gateway-xor
        Gateways & Branching — Exclusive Gateway (XOR) · 218 tokens
   8.04  @bpmnkit/docspack@0.0.1/guides.gateways.inclusive-gateway-or
        Gateways & Branching — Inclusive Gateway (OR) · 208 tokens
```

`list` shows which documentation packages were found and whether their manifests agree
with the versions installed.

## Commands

| Command | Purpose |
| --- | --- |
| `bpmnkit-docs ask <question>` | Answer from the installed docs packages — the command to give an agent |
| `bpmnkit-docs search <query>` | Rank matching chunks, for reading in a terminal |
| `bpmnkit-docs list` | Show the docs packages found and their index state |
| `bpmnkit-docs build` | Regenerate the `.llms/` payload from the docs source |

Options: `--limit <n>`, `--max-tokens <n>`, `--pack <name>`, `--cwd <dir>`.

`--pack` narrows before the index is built, not after, so asking one pack a
question does not pay for reading the others — roughly 150ms against 650ms
across both packs. A name that is not installed is an error listing what is,
rather than an empty answer that would read as "the documentation does not cover
this".

## Using the index directly

The package is also a library, so a bot, an editor extension or an MCP server can search
without shelling out:

```typescript
import { answer, discoverPacks, indexPacks } from "@bpmnkit/docspack";

const index = indexPacks(discoverPacks());
const { hits, tokens } = answer(index, "verify a worker's job type", {
  limit: 3,
  maxTokens: 3000,
});

for (const hit of hits) {
  console.log(hit.chunkId, hit.content);
}
console.log(`${tokens} tokens`);
```

## How the pack is built

`bpmnkit-docs build` reads the Markdown under `apps/landing/src/content/docs`, splits each
document at its `##` headings, and writes one file per chunk:

```
packages/docspack/
├── package.json
├── llms.txt              table of contents
└── .llms/
    ├── manifest.json     chunk ids, token counts, tags, entities
    └── chunks/
        ├── guides.gateways.exclusive-gateway-xor.md
        └── ...
```

A section too large for the budget is subdivided at `###` and then at paragraph
boundaries, never inside a fenced code block. A section too short to answer anything is
merged into the one before it, so a reference table does not become one chunk per row.
Tags come from front matter, the page's slug and the heading's own words; entities are
the qualified identifiers named in inline code.

You can steer either from the document itself:

```md
## Two-column layout

<!-- docspack: tags=grid,columns -->
<!-- docspack: entities=TwoColumn -->
```

## Trust

A manifest is third-party input that ends up in a model's context, so it is read as a
security boundary rather than as configuration:

- a chunk path that resolves outside `.llms/` is refused
- the installed `package.json` version supersedes the manifest's, and a disagreement is
  reported by `list`
- chunk ids must be unique and must match `^[A-Za-z0-9][A-Za-z0-9._-]*$`
- packages under the `@docspack-community` scope are labelled unreviewed in every answer

---

### @bpmnkit/camunda-docspack

The Camunda 8 documentation as an offline, version-locked package an AI agent can install and search — BPMN, FEEL, engine concepts and the Orchestration Cluster API.

Source: https://bpmnkit.com/docs/packages/camunda-docspack

## Overview

`@bpmnkit/camunda-docspack` packages the **Camunda 8 documentation** as a
[docspack](https://docspack.dev/spec) pack you can search offline: BPMN and FEEL
references, engine concepts, the best-practice pages, and one digest per
Orchestration Cluster API operation.

It is the companion to [`@bpmnkit/docspack`](/docs/packages/docspack), and the
split is the point. Ask ours how to *drive the library*; ask this one what the
*engine* does — gateway semantics, FEEL syntax, job activation, permissions.
Those are different questions and the right answer to one is the wrong answer to
the other.

> **This is Camunda's documentation, not BPMN Kit's.** The content is the work of
> Camunda Services GmbH and copyright in it remains with them. This package adds
> only the tooling that stages, chunks and indexes it. It is redistributed under
> **CC BY-SA 3.0**, the licence Camunda publishes it under — which is why this
> package is CC BY-SA 3.0 rather than MIT like the rest of BPMN Kit. BPMN Kit is
> not affiliated with, endorsed by or sponsored by Camunda. For canonical and
> current documentation prefer [docs.camunda.io](https://docs.camunda.io).

It is built from the `docs/` tree of
[camunda/camunda-docs](https://github.com/camunda/camunda-docs) — the unreleased
**8.10** documentation — plus the Orchestration Cluster API specification, and
rebuilt weekly.

## Installation

```sh
pnpm add -D @bpmnkit/camunda-docspack
```

There is no second CLI to learn: `bpmnkit-docs`, from
[`@bpmnkit/docspack`](/docs/packages/docspack), reads every pack installed.

## Asking it

```sh
npx bpmnkit-docs ask "how should I name an exclusive gateway" \
  --pack @bpmnkit/camunda-docspack
npx bpmnkit-docs ask "POST /jobs/activation" --pack @bpmnkit/camunda-docspack
npx bpmnkit-docs ask "what permissions does creating a process instance need" \
  --pack @bpmnkit/camunda-docspack
```

`--pack` both disambiguates and pays for itself: the index is built by reading
every chunk off disk, so narrowing to one pack is roughly 150ms against 650ms
across both. Leave it off when you do not know which pack answers.

Confirm it is installed before relying on it:

```sh
npx bpmnkit-docs list
```

```
@bpmnkit/camunda-docspack@0.1.1  1054 chunks
@bpmnkit/docspack@0.0.5  206 chunks
```

A pack missing from that list is a pack no answer can come from. See
[Using BPMN Kit with AI](/docs/guides/using-bpmnkit-with-ai) for the paragraph to
put in `AGENTS.md` or `CLAUDE.md` so an agent knows to ask both.

## What makes this corpus different

- **Diagrams as text.** The best-practice pages argue through embedded BPMN
  diagrams, and Camunda's own Markdown export drops them. Each one is rendered as
  a flow description instead, so a page about naming gateways still contains the
  gateway, its question and its conditions.
- **227 API operations.** One digest per endpoint, read from the specification
  rather than from the generated reference pages, with required permissions
  decoded, the version it appeared in, and its consistency guarantee.
- **Every chunk cites its page.** Links are rewritten to absolute
  `docs.camunda.io` URLs and each chunk ends with the page it came from.
- **Nothing dropped silently.** An MDX component the build does not recognise
  fails the build by file and line rather than quietly thinning the corpus.

## Rebuilding it

A weekly workflow (`.github/workflows/camunda-docspack.yml`) rebuilds the pack
from upstream. By hand you need a camunda-docs checkout:

```sh
node packages/camunda-docspack/dist/cli.js --camunda-docs ../camunda-docs
```

## API Reference

The published artefact is the `.llms/` payload; these exports are the build that
produces it.

| Export | Purpose |
| --- | --- |
| `build(options)` | Stage a camunda-docs checkout and write the `.llms/` payload |
| `stage(options)` | Run the staging transforms only, to a directory |
| `bpmnToText(xml)` | Render a BPMN diagram as a compact flow description |
| `readOperations(entry)` | Read one digest per operation from an OpenAPI document |
| `stripMdx(source, options)` | Reduce Camunda's MDX to indexable Markdown |
| `absoluteLinks(markdown, slug)` | Rewrite relative links to `docs.camunda.io` URLs |
| `notice(commit)` | The CC BY-SA 3.0 attribution written on every build |

## A note on the pack's name

A vendor that redistributes somebody else's documentation needs a second pack, so
this one is `@bpmnkit/camunda-docspack` rather than a second `@bpmnkit/docspack`.
The name is still a pure check inside a scope BPMN Kit owns, so the pack carries
the same trust as `@bpmnkit/docspack`.

The docspack spec originally named one pack per npm scope, and `bpmnkit-docs`
read the `-docspack` suffix ahead of it. Upstream adopted the shape in
**`docspack@1.2.0`**, so both readers now find this pack — but a `docspack` CLI
older than 1.2.0 will not, and will answer Camunda questions out of
`@bpmnkit/docspack` instead. `bpmnkit-docs` has no such floor.

---

### @bpmnkit/connectors

The Camunda 8 connector catalog, with deterministic element-template application and validation.

Source: https://bpmnkit.com/docs/packages/connectors

## Overview

`@bpmnkit/connectors` answers two questions about Camunda 8 connectors: **which ones exist**,
and **what happens to a task when you apply one**.

It bundles the 133 out-of-the-box Camunda connector templates as data, plus the
[templates BPMN Kit maintains](#templates-maintained-by-bpmn-kit), so a catalog, a search box
or an AI tool call can work offline. And it resolves a template plus a set of values into
the `zeebe:taskDefinition`, `zeebe:ioMapping` and `zeebe:modelerTemplate` bookkeeping the
Modeler would write — deterministically, so the same template and values always produce the
same XML.

The package root is browser-safe. Everything that touches the filesystem lives behind
`@bpmnkit/connectors/node`.

The catalog and application logic live in
[`@bpmnkit/core/connectors`](/docs/packages/core#connectors--bpmnkitcoreconnectors), whose
templates leave out icons, groups, tooltips and placeholders. This package re-exports that API
and adds those parts back: `getTemplate`, `applyConnectorTemplate` and
`CAMUNDA_CONNECTOR_TEMPLATES` answer with the full templates, so an applied element carries its
icon. Use it in an editor or property panel. Use the core subpath where a bundle should stay
small, for example in a worker that generates diagrams.

## Installation

```sh
npm install @bpmnkit/connectors
```

## Browsing the catalog

```typescript
import { listConnectors, searchConnectors, getTemplate } from "@bpmnkit/connectors";

listConnectors().length;        // 134 — Camunda's 133, plus BPMN Kit's
searchConnectors("slack");      // 11 matches, inbound and outbound

const template = getTemplate("io.camunda.connectors.Slack.v1");
```

`listConnectors` and `searchConnectors` return `ConnectorSummary` — the shape a picker needs,
without the full template:

```typescript
interface ConnectorSummary {
  id: string;
  name: string;
  description?: string;
  taskType: string;              // e.g. "io.camunda:http-json:1"
  appliesTo: string[];           // e.g. ["bpmn:Task"]
  direction: ConnectorDirection; // "outbound" | "inbound"
  keywords: string[];
  requiredInputs: ConnectorInputSpec[];
  optionalInputs: ConnectorInputSpec[];
}
```

Each `ConnectorInputSpec` carries what a form needs to render the field — `label`,
`description`, `default`, `choices`, whether it is `isSecret` or `isFeel`, and the `condition`
that decides whether it applies at all. `summarizeTemplate` produces the same shape from a
template you hold yourself.

`CAMUNDA_CONNECTOR_TEMPLATES` is the raw bundled array if you would rather work with the
templates directly.

### Templates maintained by BPMN Kit

`CAMUNDA_CONNECTOR_TEMPLATES` mirrors Camunda's marketplace and is regenerated from it.
Templates for services Camunda does not ship one for live beside it in
`BPMNKIT_CONNECTOR_TEMPLATES`, and join the same catalog: `listConnectors`,
`searchConnectors`, `getTemplate` and `casen connector` find them like any other. Each runs on
a connector the Camunda runtime already has — the REST connector, `io.camunda:http-json:1` —
so a cluster needs no extra job worker.

| Template id | What it does | Guide |
|---|---|---|
| `io.bpmnkit.connectors.CloudflareClef.v1` | Asks a Cloudflare Clef decision model typed questions and returns calibrated answers to route on | [AI Decisions](/docs/guides/ai-decisions) |

## Connector cards

A summary lists every input of a template. Many templates hold several operations, so GitHub's
lists `owner` five times, once per operation that uses it. A **card** is one operation with only
the inputs it uses. It is the shape to hand a language model:

```typescript
import { findConnectorCards, formatConnectorCard } from "@bpmnkit/connectors";

const [card] = findConnectorCards("create a github issue");
card.alias;      // "github"
card.operation;  // "createIssue"
card.values;     // { operationGroup: "issues", issueOperationType: "createIssue" }
card.required;   // owner, repo, issueTitle
formatConnectorCard(card);
// github createIssue — GitHub Outbound Connector: Issues / Create an issue | owner* repo* issueTitle* | optional: …
```

Pass `card.values` together with the inputs to `applyConnectorTemplate`. They select the
operation.

- **Modes.** Dropdowns that change what an operation needs without making it a different
  operation, such as an authentication type, are `card.modes`. Each choice lists the required
  inputs it adds.
- **Advanced inputs.** Inputs marked `advanced` (retries, timeouts, TLS, saved credentials) are
  left out of `formatConnectorCard` unless you pass `{ advanced: true }`.
- **Aliases.** Every bundled template has a short, fixed alias, such as `http`, `slack` or
  `sqs-message-start`, in `CONNECTOR_ALIASES`. That table also lists which dropdowns choose the
  operation. `connectorAlias(id)` and `templateIdForAlias(alias)` map between the two.

## Picking cards for a diagram

`selectConnectors({ text, tasks })` picks the cards a model should see when it connects a
diagram, per task and in code. `text` is what the person asked for; `tasks` are the diagram's
nodes. It returns only tasks with a candidate, so an empty answer means there is nothing to
connect.

A card is a candidate for a task when:
- **the task's name names the system** ("Post summary to **Slack**");
- **the request names the system,** the task is a task rather than an event, and no other
  task's name claims that system; or
- **the task's name shares a word with the connector's name,** other than a common verb.

Beyond those rules:
- **REST fallback.** The REST connector is offered for a task that asks for an HTTP call
  ("Fetch …", "Call endpoint") when nothing else fits. It is also offered for a task with no
  connector of its own when the request asks for a REST call ("check the stock with a REST
  call").
- **Synonyms.** A few words requests use for what templates call something else, such as
  "notify" for sending a message, change the ranking only.
- **Variety.** Each further card of one template ranks lower. The Email connector's IMAP
  operations do not crowd out SendGrid when the request names it.
- **Systems nobody named.** A connector that names a system the task and request do not
  ranks lower: "Azure OpenAI" for a request that says OpenAI.
- **Generic words.** A word every process has (request, document, file, data, report, record,
  form) never makes a connector a candidate by itself: "Request rework" is no SOAP request.
- **Named systems only.** A task whose name names a system gets no connector that only shares
  a word with it: "Send message to SQS" gets SQS, not Camunda's Send message connector.
- **The request wins.** A task whose name names a system the request does not ("Post summary
  to Slack" for a request that says Teams) gets the request's system first, ranked by what the
  request asks of it.
- **Deprecated templates** are never offered.
- **Caps.** At most three cards per task and eight in all. Every task keeps its best card
  before any task gets a second.

## API cards

Most systems have no dedicated connector. The REST connector can still call them, but only
with the right base URL, path and authentication. The
[API index](/docs/packages/connector-gen#api-index) has these for about 80 HTTP APIs, built
offline from their OpenAPI specs. Pass the services the request names as `apis`, and a task
that names one of them gets the REST connector first, plus an **API card** with its
best-fitting endpoints:

```typescript
import { API_SERVICES, loadApiServices } from "@bpmnkit/connector-gen/api-index";
import { apiServicesIn, formatConnectorSelection, selectConnectors } from "@bpmnkit/connectors";

const text = "When someone signs up, create a Stripe customer";
const apis = await loadApiServices(apiServicesIn(text, API_SERVICES));
const selection = selectConnectors(
  { text, tasks: [{ id: "customer", name: "Create customer", type: "serviceTask" }] },
  { apis },
);
formatConnectorSelection(selection);
// customer (Create customer):
// http — Send REST Request | url* | …
// api stripe — Stripe API https://api.stripe.com auth=bearer secret=STRIPE_TOKEN
// POST /v1/customers — Create a customer | form body: name email description address …
```

- **A dedicated connector comes first.** The API card is left out when a dedicated
  connector for the system has an operation that fits as much of the task's name. An operation
  fits a word when it does what the task's verb says and the word is what it is about:
  `createIssue` fits "Create issue", but neither it nor `getIssue` fits "List open issues". GitHub's
  connector creates issues, so "Create GitHub issue" gets it. It has nothing for workflow
  runs, so "List GitHub workflow runs" gets the API card. The request counts too: the API
  card is also left out when the connector covers every word of the request that the best
  endpoint has. "Send a confirmation email with SendGrid" gets SendGrid's connector, whatever
  the task is called.
- **Tasks only.** Events get no API card.
- **Ranking.** `findApiOperations(service, text)` ranks endpoints by the words of their
  summary, then of their path. The service's own name never counts, nor its parts ("git" and
  "hub" of GitHub), and a word a tenth of its endpoints share counts a third: "GitHub Actions"
  is in hundreds of summaries, "runs" in a few. A verb picks the method ("Create" → POST, "List" → GET), and
  a path that ends in a word of the task wins over a deeper one.
- **Services in text.** `apiServicesIn(text, summaries)` finds the services a text names by
  their brand. A brand that is also an everyday word, like "box" or "square", counts only as
  "Box API".

```typescript
import { formatConnectorSelection, selectConnectors } from "@bpmnkit/connectors";

const selection = selectConnectors({
  text: "Every hour, list open GitHub issues and post a summary to Slack",
  tasks: [
    { id: "list", name: "List open issues", type: "serviceTask" },
    { id: "post", name: "Post summary to Slack", type: "serviceTask" },
  ],
});
formatConnectorSelection(selection); // the prompt block, one task per paragraph
```

## `with` lines

In the [line format](/docs/packages/core#connectors-with-lines), a model configures a connector
with a `with` line:

```
with post: slack postMessage | channel=#ops | text== "Order " + orderId | token=xoxb-123
```

`applyConnectorLines(definitions, lines)` applies the lines from `parseProcessText` or a change
script. Each line goes through `applyTemplateToElement`, so a plain task becomes the connector's
service task and inbound templates work on events.

`resolveConnectorLine` repairs what a model gets nearly right and reports the rest:

- **A misspelt alias.** One within two letters of a real alias is read as that one (`slak` →
  `slack`).
- **The operation.** It is matched exactly, or by its last dotted part (`postMessage` →
  `chat.postMessage`), or as the start of an SDK call (`chat.completions.create` → `chat`). An
  operation the connector lacks is read as the one sharing the longest start with it, of five
  letters or more (`sendEmailImap` → `sendEmailSmtp`). It may also be given as the input that
  selects it.
- **A short key.** A key the operation lacks, but that is the end of one it has, is read as that
  one (`channel` → `data.channel`).
- **Values without a key.** `http POST https://…` sets `method` and `url`. A URL written where
  the alias goes is a REST call to it, and `api=github GET` names the method too.
- **Inputs in one part.** `| region=eu-west-1 functionName=resize` is two inputs, as the cards
  list them. A FEEL value is never split, and a `*` copied from a card (`token*=`) is dropped.
- **Results.** `result=name` sets the result variable; `result=name: expr` sets the result
  expression `={name: expr}`, under whatever key the operation uses for it.
- **Credentials.** A credential written as a value becomes a `{{secrets.…}}` placeholder: the
  diagram never carries one.
- **Variables in another syntax.** `{{orderId}}`, `{{variables.orderId}}` and `${orderId}`
  become the FEEL `=orderId`, and `${orderId}` inside a FEEL expression becomes `orderId`.
  Secrets are left as they are.
- **API index calls.** With `{ apis }` as the last argument, an `http` line that names a
  service (`http POST /v1/customers | api=stripe`), or calls a URL under its base URL, is
  completed from the index:
  - the base URL goes before the path;
  - each `{param}` of the path reads the variable of the same name;
  - the service's authentication is set with a `{{secrets.STRIPE_TOKEN}}` placeholder,
    unless the line sets its own;
  - the headers the endpoint needs are added, such as Notion's `Notion-Version` or a form
    body's `Content-Type`.

  A call the index does not have is kept, and becomes a question to check the method and
  URL. A line written like an API card's head (`api github GET /issues`) is read as
  `http GET /issues | api=github`. A service written where the alias goes
  (`stripe POST /v1/refunds`) is the same call; a connector of that name wins. A path alone, with one service loaded, is that service's. A
  FEEL `url=` beside the path is ignored: the index completes the path. A word of the path is
  spelt as the service spells it (`Actions` → `actions`). An endpoint's summary written where
  the path goes (`http GET — List workflow runs for a repository`) is read as that endpoint.
  A `{{param}}` in a path is the parameter `{param}`.

A required input the line left out becomes a **question** (`AppliedConnectorLines.questions`),
with a line to finish, and the rest of the line is still applied. A line for a node that already
carries the same connector changes only the inputs it names, so the answer to a question keeps
everything else.

- **Writing back.** `connectorLineFor(element, definitions)` writes an element's connector back
  as a line. Applying that line again gives the same element.
- **Prompting.** `CONNECT_GUIDE` is the system prompt that teaches the format to the pass that
  configures a finished diagram's connectors.

## Applying a template

Applying does not mutate an element. It turns a template plus your values into the **builder
options** for whichever element kind the template applies to, which you hand to
`@bpmnkit/core`:

```typescript
import { applyConnectorTemplate } from "@bpmnkit/connectors";
import { Bpmn } from "@bpmnkit/core";

const { serviceTask, problems } = applyConnectorTemplate("io.camunda.connectors.Slack.v1", {
  token: "=secrets.SLACK_TOKEN",
  "data.channel": "#alerts",
  "data.text": "=message",
});

// serviceTask = {
//   name: "Slack connector",
//   taskType: "io.camunda:slack:1",
//   ioMapping: { inputs: [...], outputs: [] },
//   modelerTemplate: "io.camunda.connectors.Slack.v1",
//   modelerTemplateVersion: "1",
//   modelerTemplateIcon: "data:image/svg+xml;utf8,...",
// }

Bpmn.createProcess("alerting").startEvent("in").serviceTask("notify", serviceTask).build();
```

`applyElementTemplate(template, values)` is the same operation against a template object
rather than a catalog id — the path a workspace template takes.

The result carries exactly one populated element key, so the template decides what it applies
to rather than the caller guessing:

```typescript
interface ApplyResult {
  serviceTask?: ServiceTaskOptions;
  adHocSubProcess?: Partial<AdHocSubProcessOptions>;
  startEvent?: Partial<StartEventOptions>;
  boundaryEvent?: Partial<BoundaryEventOptions>;
  intermediateEvent?: Partial<IntermediateCatchEventOptions>;
  problems: ApplyProblem[];
}
```

Nothing throws — "this value does not belong to this template" and "this required value is
missing" are answers a UI has to show, so they come back as `problems` alongside whatever
could be built:

```typescript
applyConnectorTemplate("io.camunda.connectors.Slack.v1", {}).problems;
// [{ key: "token", kind: "missing-required",
//    message: 'Missing required value for "OAuth token" (token)' }, …]

applyConnectorTemplate("nope.does.not.exist", {}).problems;
// [{ message: 'Unknown connector template "nope.does.not.exist"' }]
```

Application is deterministic: property order and the emitted bindings depend only on the
template and the values, never on iteration order or the clock. That is what lets a diagram be
rebuilt in CI and diffed.

Builder options have no field for some bindings. A message start event's correlation key and
`zeebe:linkedResource` come back as `problems` rather than being dropped, and an inbound
template's message name — which Camunda generates per element — must be passed as
`message.name`. To write every binding, apply to an element instead.

## Applying to an element — inbound connectors and linked resources

An inbound connector does not live on its element alone. Its message name and correlation key
belong to a root `bpmn:message` the event references, and an RPA task's scripts to
`zeebe:linkedResources`. `applyTemplateToElement` writes a template onto an element of a parsed
model, all of it:

```typescript
import { applyTemplateToElement, getTemplate } from "@bpmnkit/connectors";
import { Bpmn } from "@bpmnkit/core";

const webhook = getTemplate("io.camunda.connectors.webhook.WebhookConnectorIntermediate.v1")!;
const { definitions, problems } = applyTemplateToElement(
  Bpmn.parse(xml),
  "payment-received",
  webhook,
  {
    "inbound.context": "payments",
    "message.correlationKey": "=orderId",
    correlationKeyExpression: "=request.body.orderId",
  },
);

Bpmn.export(definitions);
// <bpmn:message id="Message_…" name="…">
//   <bpmn:extensionElements>
//     <zeebe:subscription correlationKey="=orderId" />
//   </bpmn:extensionElements>
// </bpmn:message>
// <bpmn:intermediateCatchEvent id="payment-received"
//     zeebe:modelerTemplate="io.camunda.connectors.webhook.WebhookConnectorIntermediate.v1" …>
//   <bpmn:extensionElements>
//     <zeebe:properties>
//       <zeebe:property name="inbound.type" value="io.camunda:webhook:1" /> …
//   <bpmn:messageEventDefinition messageRef="Message_…" />
```

What it does, binding by binding:

| Binding | Written to |
|---|---|
| `bpmn:Message#property` (`name`) | The root `bpmn:message` the event definition or receive task references |
| `bpmn:Message#zeebe:subscription#property` (`correlationKey`) | That message's `zeebe:subscription` — where Camunda reads it. A copy on the event itself is removed |
| `zeebe:property` (`inbound.type`, …) | The element's `zeebe:properties` |
| `zeebe:linkedResource` | The element's `zeebe:linkedResources`, one `zeebe:linkedResource` per `linkName` |
| everything else | As `applyElementTemplate` resolves it, on the element |

- **The element's type follows the template.** `elementType` converts the element, keeping its
  id, name and flows; `elementType.eventDefinition` makes an event a message event. A template
  whose `appliesTo` does not cover the element is refused and the model comes back unchanged —
  `bpmn:Task` covers every task type, as it does in the Modeler.
- **Messages are reused, not multiplied.** A message already carrying the name is referenced; the
  element's own message is renamed when nothing else uses it; otherwise a new one is created.
- **A generated message name is deterministic.** Camunda generates an inbound message's name as
  a UUID. Here it keeps the name of the message the element already references, or is derived
  from the template and element ids — never from a clock or random source.
- **Re-applying is safe.** Each extension kind the template declares is replaced whole, so
  switching a dropdown off removes what it wrote, and applying twice gives the model applying
  once does. `zeebe:modelerTemplate`, `…Version` and `…Icon` are stamped the same way.
- **The input is never mutated.** The result is a copy.

The keys for these properties, where the template gives no `id`, are `message.name`,
`message.correlationKey` and `linkedResource.<linkName>.<property>` — for example
`linkedResource.RPAScript.resourceId`. `listConnectors` reports them like any other input.

## Workspace templates

A project can ship its own `.camunda/element-templates/`. The filesystem half lives behind its
own entry point so importing the catalog in a browser never pulls in `node:fs`:

```typescript
import { discoverElementTemplates, collectElementTemplates } from "@bpmnkit/connectors/node";
```

- `discoverElementTemplates` walks **upward** from a diagram to the project root, nearest
  winning — the resolution a modeler needs.
- `collectElementTemplates` walks **downward** from a root — the sweep a CI check needs, so a
  broken template in a sub-folder is reported rather than skipped because the root looked fine.

`registerElementTemplates` merges what you found into the catalog, later registration winning
on an id collision, so `listConnectors`, `searchConnectors` and `getTemplate` then see a
project's own templates alongside the bundled ones. `clearRegisteredTemplates` undoes it.

### Which host resolves how

Per-file resolution is what Camunda Desktop Modeler does: a diagram in `a/` sees
`a/.camunda/element-templates/` and every folder above it up to the project root, and never
`b/`'s. When two folders define the same id, the one nearer the diagram wins.

| Host | Resolution |
|---|---|
| `casen lint`, `casen dev` checks | Per file. Each diagram's `connector/*` findings use the templates from its folder up to the project root (`casen lint`: the current directory; `casen dev`: the served folder), then the bundled catalog. |
| VS Code extension | Per file. The extension host calls `discoverElementTemplates` directly — no proxy — with the workspace folder as the root, and the Problems panel checks connector inputs against them. |
| Studio (project opened from disk) | Per file. The connector-catalog plugin asks the proxy for `GET /element-templates?root=<project>&file=<model path>` and swaps the set when you open another model. |
| `casen connector list/search/show` | Upward from the current directory. |
| `casen connector validate` | Downward: every template in the project (`collectElementTemplates`). |
| bpmnkit.com/editor, Drop | Bundled templates only. A browser with no filesystem has no path to resolve from. |

In a browser host, the [connector-catalog plugin](/docs/packages/plugins) does the swapping:

```typescript
const catalog = createConnectorCatalogPlugin(configPanelBpmn, palette, {
  proxyUrl: "http://localhost:3033",
  workspaceRoot: "/home/me/project",
  diagramPath: "processes/orders/order.bpmn", // absolute, or relative to workspaceRoot
});

// The user opened another diagram:
await catalog.setDiagramPath("processes/billing/invoice.bpmn");
```

The proxy serves `/element-templates` only for a `workspaceRoot` it accepts as a workspace: a
folder passed with `casen proxy start --root`, or a project folder that is not your home
directory, the filesystem root or a hidden folder. The diagram path must resolve inside that
root. See [Local proxy](/docs/cli/casen#local-proxy).

The previous diagram's templates are unregistered before the next diagram's are registered, and
a bundled template they shadowed comes back, so the properties panel's connector picker lists
only the current diagram's templates plus the bundled and built-in ones. A host that resolves
templates itself (with its own filesystem access) passes them with
`catalog.setWorkspaceTemplates(templates)` instead. Without `diagramPath`, `workspaceRoot` keeps
the project-wide merge (`GET /element-templates?root=…`).

## Validating a template

```typescript
import { validateElementTemplate } from "@bpmnkit/connectors";

validateElementTemplate(template);
// {
//   valid: false,
//   problems: [
//     { path: 'properties[0].type',
//       message: 'unknown property type "nope" — expected one of String, Text, Hidden, Dropdown, Boolean, Number' },
//     { path: 'properties[0].binding', message: 'binding is required' },
//   ],
//   warnings: [],
// }
```

Problems are reported by **path** rather than as a JSON-schema `oneOf` dump, and every problem
is collected rather than stopping at the first. Warnings are kept separate from problems, so a
CI gate can fail on one and not the other. `readTemplateDocument` parses a file that may hold
one template or an array of them.

The CLI wraps this as [`casen connector validate`](/docs/cli/connector), which exits non-zero
for CI and takes `--format json`.

## API Reference

| Export | Description |
|---|---|
| `listConnectors()` | Every connector in the catalog, as summaries |
| `searchConnectors(query)` | Summaries matching name, description or keywords |
| `getTemplate(id)` | The full `ElementTemplate` for an id |
| `summarizeTemplate(template)` | `ConnectorSummary` from a template you hold |
| `propertyKey(property)` | The variable name a template property binds to |
| `applyConnectorTemplate(id, values)` | Catalog template → builder options + problems |
| `applyElementTemplate(template, values)` | Template object → builder options + problems |
| `applyTemplateToElement(definitions, elementId, template, values)` | Template written onto an element of a parsed model → `{ definitions, problems }` |
| `validateElementTemplate(template)` | `{ valid, problems, warnings }` |
| `readTemplateDocument(text)` | Parse a file holding one template or many |
| `registerElementTemplates(templates)` | Merge templates into the catalog |
| `clearRegisteredTemplates()` | Drop everything registered |
| `CAMUNDA_CONNECTOR_TEMPLATES` | The 133 bundled Camunda templates, raw |
| `BPMNKIT_CONNECTOR_TEMPLATES` | The templates BPMN Kit maintains, raw |
| `findConnectorCards(query, { limit })` | Operation cards matching a request, best first |
| `connectorCards(id)` / `listConnectorCards()` | The cards of one template / of all |
| `formatConnectorCard(card, { advanced })` | A card as one prompt line |
| `connectorAlias(id)` / `templateIdForAlias(alias)` | Template id ↔ short alias |
| `CONNECTOR_ALIASES` | Alias and operation dropdowns of every bundled template |
| `applyConnectorLines(definitions, lines, { apis })` | Apply `with` lines → `{ definitions, problems, fixes, questions }` |
| `resolveConnectorLine(line, { apis })` | One `with` line → template, card, values, problems, fixes, questions |
| `connectorLineFor(element, definitions)` | An element's connector as a `with` line |
| `CONNECT_GUIDE` | System prompt teaching `with` lines |
| `selectConnectors({ text, tasks }, { perTask, total, apis })` | The cards, and API cards, to show a model for each task of a diagram |
| `formatConnectorSelection(selection)` | Picked cards as a prompt block |
| `apiServicesIn(text, summaries)` | Ids of the API-index services a text names |
| `findApiOperations(service, text, { limit })` / `rankApiOperations` | A service's endpoints that fit a task, best first |
| `formatApiCard({ service, operations })` | An API card for a prompt |
| `findApiOperation(service, method, path)` | The indexed endpoint a call names |
| `apiUrl(baseUrl, path)` / `apiAuthValues(service)` / `apiSecretNames(service)` | REST connector inputs for an indexed call |

From `@bpmnkit/connectors/node`: `discoverElementTemplates`, `collectElementTemplates`,
`DEFAULT_CONFIG_FOLDER`, `TEMPLATES_SUBFOLDER`.

## Stability

`@bpmnkit/connectors` carries the [1.0 stability promise](/docs/getting-started/stability):
its exports will not change shape without a major version.

Two things the promise does **not** freeze, because both track Camunda rather than this
package:

- **The catalog's contents.** Connectors are added, and upstream templates gain versions and
  properties. A changed `CAMUNDA_CONNECTOR_TEMPLATES` is a minor; the types describing it are
  covered as usual.
- **Template validation being strict about new upstream shapes.** A template that validates
  today will not start failing in a minor — that direction *is* covered.

---

### @bpmnkit/operate

Lightweight monitoring and operations UI for Camunda 8 dev clusters, Camunda 8 Run and SaaS trials.

Source: https://bpmnkit.com/docs/packages/operate

`@bpmnkit/operate` is a small, Operate-like web UI for a Camunda 8 cluster. Mount it in
any element to get a dashboard and lists of process definitions, decisions, process
instances, incidents, jobs and user tasks, with detail pages that draw the BPMN diagram.
It is built for development clusters, [Camunda 8 Run](https://docs.camunda.io/docs/self-managed/quickstart/developer-quickstart/c8run/)
and SaaS trial clusters. It is not a replacement for Camunda Operate in production.

The UI does not call the cluster itself. It talks to the BPMN Kit proxy
(`@bpmnkit/proxy`, started with `casen proxy start`). The proxy holds your connection
profiles and credentials, and adds the auth header to each Camunda request.

```
browser (Operate)  ──fetch──▶  BPMN Kit proxy :3033  ──REST + auth──▶  Orchestration Cluster API /v2
```

## What it does, and what it does not do

Compared with [Camunda Operate](https://docs.camunda.io/docs/components/operate/operate-introduction/):

| | `@bpmnkit/operate` | Camunda Operate |
|---|---|---|
| Dashboard counts (active instances, open incidents, active jobs, pending tasks, definitions) | Yes | Yes |
| Process definitions and versions, with the diagram | Yes | Yes |
| Decision definitions, with the DMN table | Yes | Yes |
| Process instance list, filter by state and root process | Yes, client side | Yes, server side |
| Instance diagram with active and completed elements | Yes | Yes |
| Instance variables (read) | Yes | Yes |
| Edit variables | No | Yes |
| Cancel one process instance | Yes | Yes |
| Start a process instance (with business ID and variables) | Yes | No |
| Incidents: retry job (sets retries to 3), resolve incident | Yes | Yes |
| Jobs list | Yes | No |
| User tasks list and form preview | Yes (read only) | No (Tasklist) |
| Publish / correlate a message, broadcast a signal | Yes | No |
| AI incident analysis and natural-language search | Yes, if the proxy has an AI CLI | No |
| Process instance modification and migration | No | Yes |
| Batch operations (cancel, resolve, migrate, modify, delete) | No | Yes |
| Decision instance history | No | Yes |
| Deleting instances | No | Yes |
| Large result sets | No: each list loads at most 1000 items | Yes |
| Users, roles, authorizations, multi-tenancy UI | No: whatever the proxy profile may do | Yes |
| Real-time push | No: the browser polls (30 s by default) | Periodic refresh |

Use it to look at what your process is doing while you build it. Use Camunda Operate
when you need history, bulk operations or access control.

## Installation

```sh
npm install @bpmnkit/operate
npm install -g @bpmnkit/cli   # provides `casen proxy start` and `casen profile`
```

## Quick start

### 1. Try it without a cluster

Mock mode uses built-in fixture data and makes no network calls:

```typescript
import { createOperate } from "@bpmnkit/operate"

createOperate({
  container: document.getElementById("app")!,
  mock: true,
})
```

Operate fills its container (`height: 100%`), so give the container a height.

### 2. Camunda 8 Run

Camunda 8 Run serves the Orchestration Cluster REST API at `http://localhost:8080/v2`,
with no authentication by default.

```sh
casen profile create c8run --base-url http://localhost:8080/v2 --auth-type none
casen profile use c8run
casen proxy start                 # http://localhost:3033
```

If you turned on Basic authentication in Camunda 8 Run's `application.yaml`, create the
profile with `--auth-type basic --username <user> --password <password>`.

### 3. Camunda SaaS (trial) cluster

SaaS requires an OAuth access token. Create client credentials for the cluster in the
Camunda Console and download the credentials file. Import it as a profile:

```sh
casen profile import saas ./camunda-credentials.sh   # reads ZEEBE_REST_ADDRESS, CAMUNDA_CLIENT_ID, …
casen profile use saas
casen proxy start
```

Or create it by hand. The base URL is the cluster's REST address plus `/v2`:

```sh
casen profile create saas \
  --base-url https://<region>.zeebe.camunda.io/<cluster-id>/v2 \
  --auth-type oauth2 --client-id <id> --client-secret <secret> \
  --token-url https://login.cloud.camunda.io/oauth/token --audience zeebe.camunda.io
```

The proxy gets and caches the token. The client needs permission for the operations you
use; otherwise Camunda answers `403 Forbidden`.

### 4. Mount Operate against the proxy

```typescript
import { createOperate } from "@bpmnkit/operate"

const operate = createOperate({
  container: document.getElementById("app")!,
  proxyUrl: "http://localhost:3033", // default
  profile: "c8run",                  // optional: the proxy's active profile if omitted
  pollInterval: 15_000,              // optional: default 30 000 ms, minimum 5 000, 0 = load once
})
```

The header has a profile selector with every profile the proxy knows. A change reloads
the current view against the new profile.

## Connection, CORS and security notes

- **The browser never sees Camunda credentials.** They stay in the proxy's profile
  store. Operate sends only the profile name (`?profile=` on the monitoring poll and the
  `x-profile` header on API calls).
- **CORS.** The proxy answers only allowed origins: bpmnkit.com, Studio, the desktop app,
  and any `localhost`, `127.0.0.1` or `[::1]` origin on any port (for example a Vite dev
  server on `:5173`). It sends that origin back in `Access-Control-Allow-Origin`, never
  `*`. A page on any other origin gets `403`. To embed Operate in an app on another
  origin, start the proxy with `casen proxy start --allow-origin https://your.app`. You do
  not need to configure CORS on the cluster, because the browser does not call it.
- **Same-origin reverse proxy.** `proxyUrl` can be relative. If your dev server forwards
  `/bpmnkit-proxy/*` to `http://localhost:3033/*`, use `proxyUrl: "/bpmnkit-proxy"`. Keep
  the forwarded `Host` header a loopback name (the default for the Vite proxy), or allow
  your host name with `--allow-host`.
- **Keep the proxy on a trusted machine.** It acts with the stored credentials for any
  caller it lets in. By default it listens only on loopback; `--host` exposes it to the
  network. See [Local proxy](/docs/cli/casen#local-proxy).
- **Errors.** When a poll fails, Operate shows the reason above the view, for example
  `HTTP 401: No active profile` (no profile with a base URL) or
  `Connection error. Retrying…` (the proxy is not running). The last good data stays on
  screen, and the message goes away after the next good poll.

## API reference

### `createOperate(options): OperateApi`

```typescript
interface OperateOptions {
  container: HTMLElement
  proxyUrl?: string        // default "http://localhost:3033"; may be relative
  profile?: string         // default: the proxy's active profile
  theme?: "light" | "dark" | "auto" | "neon"  // default "light"
  pollInterval?: number    // ms; default 30 000, minimum 5 000, 0 = load once, no refresh
  mock?: boolean           // fixture data, no network; default false
  onOpenInEditor?: (xml: string, name: string) => void  // shows "Open in Editor" on diagrams
}

interface OperateApi {
  readonly el: HTMLElement              // the root element appended to container
  setProfile(name: string | null): void // null = the proxy's active profile; reloads the view
  setTheme(theme: Theme): void          // also re-themes an open diagram
  navigate(path: string): void          // e.g. "/instances/2251799813690001"
  destroy(): void                       // stops polling and removes the UI
}
```

A theme the user picked in the header is saved in `localStorage` and takes precedence
over `options.theme` on the next load.

The package also exports the Camunda result types it displays (`ProcessInstanceResult`,
`IncidentResult`, `JobSearchResult`, `UserTaskResult`, `VariableResult`,
`ProcessDefinitionResult`), `ProfileInfo` (the shape of the proxy's `GET /profiles`) and
`DashboardData` (the dashboard poll payload).

`createInstanceDetailView`, `createDefinitionDetailView`, `createDecisionDetailView`,
`InstancesStore`, `DefinitionsStore` and `DecisionsStore` are also exported. They are
marked `@internal`: BPMN Kit Studio uses them, and they can change in any release.

### Routes

Operate uses hash routes, so it works from any static host:

| Route | View |
|---|---|
| `#/` | Dashboard |
| `#/definitions`, `#/definitions/:key` | Process definitions, definition detail |
| `#/decisions`, `#/decisions/:key` | Decision definitions, decision detail |
| `#/instances`, `#/instances/:key` | Process instances, instance detail |
| `#/incidents`, `#/incidents/:key` | Incidents, incident detail |
| `#/jobs` | Jobs |
| `#/tasks`, `#/tasks/:key` | User tasks, task detail |
| `#/messages` | Message and signal actions, active message subscriptions |
| `#/search` | Instance and variable search |

## Limits

- Each list asks the proxy for at most 1000 items, newest first. Search, sort and
  paging in the tables happen in the browser, over those items.
- The instance detail loads the first page of variables and element instances that
  the search endpoints return. A very large instance can show an incomplete list.
- The browser polls. Each poll is one request to the proxy, which makes one or more
  search requests to the cluster, so keep `pollInterval` high for shared clusters.

---

## Documentation — CLI

### casen CLI

Interactive TUI for managing Camunda 8 clusters from the terminal.

Source: https://bpmnkit.com/docs/cli/casen

`casen` is an interactive terminal UI (TUI) for managing Camunda 8. Navigate with arrow keys,
no flags to memorize.

## Installation

```sh
pnpm add -g @bpmnkit/cli
```

## Quick Start

```sh
casen
```

The main menu appears. Use ↑ ↓ to navigate, Enter to select, Escape to go back.

## Navigation Structure

```
casen
├── generate        — generate or modify BPMN files without the TUI (alias: gen)
│   ├── bpmn        — templates, CompactDiagram JSON, or patch existing files
│   └── types       — TypeScript types for job workers, generated from BPMN
├── view            — view BPMN, DMN, and form files in the browser
│   ├── open        — any mix of .bpmn/.dmn/.form files or folders (auto-detect)
│   ├── bpmn        — BPMN diagrams rendered as SVG
│   ├── dmn         — DMN decision tables
│   └── form        — Camunda form layouts
├── lint            — static analysis and auto-fix for BPMN files
│   ├── lint        — run all checks, report findings
│   └── improve     — AI-assisted improvement suggestions
├── story           — render a BPMN process as a narrative HTML page
├── migrate         — migrate models from other engines to Camunda 8
│   └── c7          — convert Camunda 7 models and report the manual work
├── ask             — ask an AI assistant about your process or cluster
├── connector       — generate element templates from OpenAPI specs
│   ├── generate    — generate templates from a spec file or catalog entry
│   └── catalog     — list built-in catalog entries
├── profile         — manage connection profiles
│   ├── list        — show all profiles
│   ├── add         — create a new profile
│   └── switch      — set the active profile
├── process
│   ├── list        — list deployed process definitions
│   ├── start       — start a new instance
│   ├── instances   — list running instances
│   └── cancel      — cancel an instance
├── job
│   ├── list        — list active jobs
│   ├── complete    — complete a job
│   └── fail        — fail a job with a message
├── incident
│   ├── list        — list open incidents
│   └── resolve     — resolve an incident
├── decision
│   ├── list        — list deployed DMN decision tables
│   └── evaluate    — evaluate a decision with test inputs
├── variable
│   ├── list        — list variables for an instance
│   └── update      — set a variable value
├── message
│   └── publish     — publish a message for correlation
├── worker          — run job workers
│   ├── <job-type>  — auto-complete worker for a job type
│   └── start       — start scaffolded workers from ./workers/
├── proxy           — start the local AI bridge server
└── plugin          — manage CLI plugins
    ├── search      — discover plugins on npm
    ├── install     — install a plugin from npm or a local path
    ├── list        — list installed plugins
    ├── update      — update one or all plugins
    ├── remove      — uninstall a plugin
    └── info        — show details for an installed plugin
```

## Generate BPMN files

`casen generate bpmn` creates BPMN files from the command line — no interactive menu required.
Choose a built-in template, supply a full CompactDiagram JSON definition, or patch an existing file.

```sh
casen generate bpmn --template approval --process-id leave-request
casen generate bpmn --input order.bpmn --dump-compact   # inspect as JSON for AI
casen generate bpmn --input order.bpmn --patch '{"elements":[...],"flows":[...]}'
```

`casen gen types` turns BPMN files into TypeScript types for job workers — job types, their
variables, output and headers, message names and error codes — and can check that every job type has
a worker:

```sh
casen gen types processes/ --out src/generated/bpmn-types.ts
casen gen types processes/ --check-workers "src/**/*.ts" --strict
```

See [casen generate](/docs/cli/generate) for full documentation.

## Start from a gallery template

`casen template` writes one of the runnable templates from the [gallery](/templates) into your
project. You get the `.bpmn`, a `.bpmn.tests.json` file with its scenarios, and any `.dmn` or
`.form` files the process uses. The skeletons from `casen generate bpmn --template` are empty
starting shapes. A gallery template is a complete process with its job types, mappings and
tests.

```sh
casen template list --category approvals
casen template use expense-approval processes/   # --force overwrites existing files
```

See [Process Templates](/docs/guides/templates) for what each template contains and how to
run its scenarios.

## View BPMN, DMN, and Form files

`casen view` opens a local browser-based viewer. Accepts individual files, folders, or a mix.

```sh
casen view bpmn ./processes/     # all .bpmn files in a folder
casen view dmn routing.dmn       # DMN decision table
casen view open ./project/       # any mix of .bpmn/.dmn/.form
```

See [casen view](/docs/cli/view) for full documentation.

## Connection Profiles

A profile stores the connection details for a Camunda cluster:

```sh
# Add a new profile
casen profile add

# You'll be prompted for:
# Name: my-saas-cluster
# Base URL: https://api.cloud.camunda.io
# Auth type: oauth2 | bearer | none
# Client ID, Client Secret, Audience, Token URL (for oauth2)
```

Profiles are saved to `~/.casen/profiles.json`.

## Common Workflows

### List process definitions

```
Navigate to: process → list → Enter

Result:
  bpmnProcessId                name                    ver
  ──────────────────────────────────────────────────────────
▶ invoice-approval              Invoice Approval          2
  order-fulfillment             Order Fulfillment         1
  customer-onboarding           Customer Onboarding       3
```

### Start a process instance

```
Navigate to: process → start → Enter

Select process: invoice-approval
Variables (JSON): {"invoiceId": "inv-001", "amount": 5000}
```

### Resolve an incident

```
Navigate to: incident → list → Enter
```

Select the incident with Enter, choose "Resolve" from the action menu.

### Publish a message

```
Navigate to: message → publish → Enter

Message name: payment-confirmed
Correlation key: ord-456
Variables (JSON): {"method": "card"}
```

## Plugins

casen's plugin system lets you extend the CLI with new command groups — your own organisation's
workflows, third-party integrations, or community-built tools.

### Discover plugins

```sh
# Browse all published casen plugins
casen plugin search

# Search by keyword
casen plugin search deploy
casen plugin search slack
```

Results are fetched live from the npm registry. Any package tagged with the `casen-plugin` keyword
appears here.

### Install a plugin

```sh
# Install from npm
casen plugin install casen-deploy

# Install a local plugin during development
casen plugin install ./my-plugin
```

Plugins are installed into `~/.casen/plugins/` and loaded automatically the next time casen starts.

### Manage installed plugins

```sh
# List installed plugins
casen plugin list

# Show full details for one plugin
casen plugin info casen-deploy

# Update a single plugin to the latest version
casen plugin update casen-deploy

# Update all installed plugins
casen plugin update

# Remove a plugin
casen plugin remove casen-deploy
```

Once installed, plugin commands appear in the main TUI and in tab-completion alongside built-in commands.

To build your own plugin, see [Plugin Authoring](/docs/cli/plugin-authoring).

## BPMN generation pipeline

Every BPMN process is authored as a `ProcessPlan` JSON file — never hand-written XML — and
compiled deterministically:

```sh
# Print the ProcessPlan JSON format reference (schema + field notes)
casen plan schema

# Compile a plan to laid-out, deployable BPMN
casen synth synth order-process.plan.json --output order-process.bpmn

# Extend an existing process: lift it back to plan form, then merge a delta plan into it
casen plan extract order-process.bpmn
casen synth synth delta.plan.json --merge order-process.bpmn --output order-process.bpmn

# Find and inspect a Camunda connector template
casen connector search slack
casen connector show io.camunda.connectors.Slack.v1

# Deploy-readiness gate, then deploy
# (a .bpmnlintrc in the diagram's folder or above is honoured; --no-bpmnlintrc ignores it)
casen lint lint order-process.bpmn --profile deploy
casen deploy deploy order-process.bpmn                   # local Reebe
casen deploy deploy order-process.bpmn --target camunda8 # active Camunda 8 profile
```

`casen synth` reports any problems keyed by JSON path in the plan (e.g. `steps[2].connector.values.token`) — fix the plan, never the XML, and re-run. If the plan has a `tests` array, `casen synth` also writes a `<file>.bpmn.tests.json` sidecar, runnable with `casen test <file>.bpmn`.

`--check` also proves the result runs:
- It [dry-runs](/docs/guides/testing-processes#dry-run) each process once, with every
  connector and job mocked.
- It lists the secrets the diagram reads, to create in the cluster before deploying.

A run that cannot reach its end fails the command:

```
$ casen synth synth order-process.plan.json --check
✓ Wrote order-process.plan.bpmn
✓ Dry run of order-validation-failed reaches "Ops notified" · 1 connector(s) mocked
Secrets to create in the cluster before deploying:
  SLACK_OAUTH_TOKEN — "Slack Outbound Connector"
```

With `--json`, the findings are in the output's `check` field.

See [Building Processes with AI](/docs/guides/ai-implement) and [AI Agents](/docs/guides/ai-agents) for full walkthroughs.

`casen lint` reads a `.bpmnlintrc` if your project has one. See
[bpmnlint Compatibility](/docs/guides/bpmnlint) for how the rules map and how to run your
own `bpmnlint-plugin-*` rules.

## AIKit Skills

`casen` ships four lightweight, CLI-only Claude Code slash commands (no MCP server, no proxy):

```sh
casen skills install
```

| Command | Description |
|---|---|
| `/implement <description>` | Write a plan, compile it, test it, scaffold workers, deploy |
| `/review <path>` | Run the full lint report and report a deploy-ready verdict |
| `/test <path>` | Run scenario tests and report path/branch coverage |
| `/deploy <path>` | Deploy-readiness gate, then deploy to local Reebe or Camunda 8 |

For the richer skill set (`/bpmnkit:implement`, `:extend`, `:agent`, `:connect`, plus generated reference docs), install the Claude Code plugin instead: `/plugin marketplace add github:bpmnkit/bpmnkit` then `/plugin install bpmnkit`. See [AIKit Skills](/docs/cli/skills) for full documentation.

## Worker commands

```sh
# Run a simple auto-complete worker (for testing)
casen worker payment-service

# Start scaffolded workers from ./workers/
casen worker start

# Start a specific scaffolded worker
casen worker start send-invoice
```

## Agent workforce

Hire coding-agent CLIs as durable job workers. They serve the `.agent()` steps of
[`@bpmnkit/flow`](/docs/packages/flow) flows — any service task with job type `agent:<role>` or
`agent:<rank>:<role>` and a `prompt` task header. See
[Durable Agent Flows](/docs/guides/durable-agent-flows).

```sh
# Hire: everything after -- is the command; the prompt goes on stdin unless an argument has {prompt}
casen agent hire claude --roles plan,pr-review --rank senior -- claude -p
casen agent hire copilot --roles feature --instances 3 -- copilot -p "{prompt}"

casen agent list            # hired agents and the job types they serve
casen agent fire copilot    # remove one
casen agent work            # run the workforce against the active profile until Ctrl+C
```

## Local engine (Reebe)

Reebe is a **dev/test** workflow engine (~50 MB) that serves the Zeebe API locally, so you
can deploy and run processes on your machine or in CI without a Camunda 8 cluster. It is
[Experimental](/docs/getting-started/stability#product-tiers) and single-node: do not run it
in production. Reebe is a clean-room implementation written from Camunda's public
documentation, and is not affiliated with or endorsed by Camunda. "Zeebe" and "Camunda" are
trademarks of Camunda Services GmbH.

```sh
# Embedded SQLite, no external database
casen reebe start

# REST on 26500, where ZEEBE_ADDRESS points by default. The gRPC gateway uses 26500
# unless told otherwise, so move it out of the way.
casen reebe start --port 26500 --grpc-port 26501

# PostgreSQL instead of the embedded database
casen reebe start --database-url postgres://user:pass@localhost/reebe
```

| Flag | Default | Description |
|---|---|---|
| `--port` | `8080` | HTTP (REST) port to listen on |
| `--grpc-port` | `26500` | Zeebe gRPC gateway port; must differ from `--port` |
| `--database-url` | embedded SQLite | PostgreSQL connection URL |
| `--config` | `config.toml` | Path to the engine config file |

`casen reebe` on its own is shorthand for `casen reebe start`. The command runs the
`reebe-server` binary. If it is not on your `PATH`, build the embedded (SQLite) server with
`cargo install --path apps/reebe/crates/reebe-server --no-default-features --features embedded`,
or the PostgreSQL one — which needs `--database-url` — without the two feature flags.

## Local proxy

`casen proxy start` (or `casen proxy`) starts the local proxy on port 3033. Studio, the
bpmnkit.com editor and Operate page, and the desktop app use it for AI, deploys, Camunda API
calls with your stored profiles, and Studio's project folders.

```sh
casen proxy start
```

| Flag | Default | Description |
|---|---|---|
| `--port <n>` | `3033` | Port to listen on. |
| `--host <addr>` | loopback | Interface to listen on. By default the proxy listens on `127.0.0.1` and `::1` only. Any other value exposes it to the network and prints a warning. |
| `--allow-origin <list>` | — | Extra browser origins that may call the proxy, comma-separated. |
| `--allow-host <list>` | — | Extra `Host` names the proxy answers to, comma-separated. You need this with `--host 0.0.0.0`. |
| `--root <list>` | — | Folders the file routes may always use, separated like `PATH` (`:` on macOS and Linux, `;` on Windows). |

The same settings are read from `BPMNKIT_PROXY_HOST`, `BPMNKIT_PROXY_ALLOWED_ORIGINS`,
`BPMNKIT_PROXY_ALLOWED_HOSTS` and `BPMNKIT_PROXY_ROOTS`, for example when you run the
`bpmn-ai-server` binary directly. Flags add to the lists from the environment.

### Who can use the proxy

The proxy acts with your Camunda credentials and reads and writes files. Any web page open in
your browser can send requests to `localhost`, so the proxy checks every request:

- **Origin.** A browser request must come from `https://bpmnkit.com`,
  `https://bpmnkit-studio.pages.dev`, the desktop app
  (`tauri://localhost`, `http(s)://tauri.localhost`), any `localhost`, `127.0.0.1` or
  `[::1]` origin on any port, or an origin you allow with `--allow-origin`. Other origins get
  `403` and no CORS headers. Cross-site browser requests without an `Origin` header, such as
  an image tag, are also refused. Programs that send no `Origin` (the CLI, the MCP server,
  `curl`) are served.
- **Host.** A request must name the proxy as `localhost`, `127.0.0.1` or `[::1]`, or as a
  host you allow with `--allow-host`. This stops DNS-rebinding pages.
- **Files.** The `/fs/*` routes and `/element-templates` work only inside workspace roots:
  folders you pass with `--root`, and project folders Studio opens. The proxy does not open
  the filesystem root, your home directory, a folder that contains your home directory, or a
  hidden folder such as `~/.ssh` unless you pass it with `--root`. Inside a root, only
  `.bpmn`, `.dmn`, `.form` and `.md` files (and their `.bpmnkit` metadata) can be read,
  written, moved or deleted. Paths with `..`, and symlinks that lead out of the root, are
  refused.
- **AI CLIs.** The AI routes (`/chat`, `/improve`, `/operate/chat`,
  `/operate/incident-assist`, `/operate/ai-search`), the `io.bpmnkit:llm:1` worker and
  `casen ask` start `claude`, `copilot` or `gemini` with permission checks on and no
  built-in tools: the model cannot run commands, read or write files, or open URLs. Each run
  starts in an empty temporary folder and loads none of your own MCP servers, settings,
  plugins or extensions. A `/chat` run that edits a diagram gets only the proxy's diagram
  tools (`get_diagram`, `compose_diagram`, `add_elements`, `remove_elements`,
  `update_element`, `set_condition`, `add_http_call`, `find_connectors`, `add_connector`,
  `replace_diagram`); they change the diagram in the MCP server's memory, and
  `compose_diagram` runs the model's code in an isolated V8 isolate. The connector tools also
  read the bundled connector catalog and API index, and nothing else. Chat text, diagrams,
  incident details and variable values reach the model fenced as untrusted data.

| CLI | Flags the proxy passes |
|---|---|
| `claude` | `-p --system-prompt … --tools "" --strict-mcp-config --setting-sources "" --permission-mode dontAsk --disable-slash-commands --no-session-persistence`, plus `--mcp-config <run config> --allowedTools mcp__bpmn__…` for diagram edits. The conversation goes on stdin. |
| `copilot` | `-p … --deny-tool=shell --deny-tool=write --deny-tool=url --disable-builtin-mcps --no-custom-instructions --no-ask-user --disallow-temp-dir`, plus `--additional-mcp-config @<run config> --allow-tool=bpmn(<tool>)` per diagram tool. |
| `gemini` | `--prompt … --approval-mode default --admin-policy <deny-all> --policy <deny-all> --extensions none --skip-trust`, where the policy denies every tool and trust covers only the empty run folder. |

To use the proxy from your own web app, allow its origin:

```sh
casen proxy start --allow-origin https://modeler.example.com
```

To reach the proxy from another machine, which gives that network your credentials and
files, listen on all interfaces and name the host clients use:

```sh
casen proxy start --host 0.0.0.0 --allow-host devbox.lan
```

## MCP Server Mode

`casen proxy mcp` starts BPMN Kit's MCP (Model Context Protocol) server on stdio, so Claude
Code, Claude Desktop, Cursor or any MCP client can create, validate, simulate and deploy
processes, and call any Camunda 8 REST operation through `camunda_search` and
`camunda_execute`:

```sh
casen proxy mcp
```

Configure it in Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bpmnkit": {
      "command": "casen",
      "args": ["proxy", "mcp"]
    }
  }
}
```

The server uses the active `casen` profile for cluster calls; set one with `casen profile`
first, or pass `ZEEBE_ADDRESS`, `ZEEBE_CLIENT_ID` and `ZEEBE_CLIENT_SECRET` in `env`. The
full tool list is in the [AI guide](/docs/guides/ai#mcp-server).

Now you can ask Claude: _"Show me the open incidents on the invoice-approval process"_ or
_"Resolve all incidents on process instance 2251799813685249"_.

---

### casen generate

Generate BPMN files from built-in templates, CompactDiagram JSON, or by patching an existing file — and TypeScript types for job workers from BPMN.

Source: https://bpmnkit.com/docs/cli/generate

`casen generate bpmn` produces BPMN 2.0 files without the interactive TUI. It has three operating
modes: template, definition (full JSON), and modify-existing (patch). Auto-layout is applied in all modes.

## Commands

```
casen generate          (alias: casen gen)
├── bpmn    — generate or modify a BPMN file
└── types   — generate TypeScript types from BPMN; check workers against it
```

## Template mode

Pick a built-in template by name. Use `--process-id` and `--name` to customise the identifiers.

```sh
casen generate bpmn --template minimal --process-id order --name "Order Processing"
casen generate bpmn --template approval --process-id leave-request
casen generate bpmn --template parallel --process-id enrichment --name Enrichment
casen generate bpmn --template timer-start --process-id nightly-sync
```

| Template | Pattern |
|---|---|
| `empty` | Start event only — bare skeleton |
| `minimal` | Start → service task → end |
| `user-task` | Start → user task → end |
| `call-activity` | Start → call activity → end |
| `business-rule` | Start → business rule task → end |
| `approval` | Start → user task → XOR gateway → approve/reject paths |
| `parallel` | Start → parallel fork → 2 service tasks → join → end |
| `inclusive` | Start → inclusive gateway → 2 conditional tasks → merge → end |
| `timer-start` | Timer start event → service task → end |
| `message-start` | Message start event → service task → end |
| `error-boundary` | Service task with error boundary → two end events |
| `subprocess` | Start → embedded sub-process → end |
| `event-subprocess` | Process with a non-interrupting error event sub-process |

### Flags

| Flag | Short | Description | Default |
|---|---|---|---|
| `--template` | | Template name (see table above) | `minimal` |
| `--process-id` | `-i` | Process element ID | `process` |
| `--name` | `-n` | Process display name | — |
| `--output` | `-o` | Output file path (`-` for stdout) | `<process-id>.bpmn` |

## Definition mode (AI / scripting path)

Pass a full **CompactDiagram** JSON object directly. This covers all 23 BPMN element types, all event
definition types, boundary events, sub-processes, and Zeebe extensions.

```sh
# Inline JSON
casen generate bpmn --definition '{"id":"Definitions_order","processes":[...]}'

# Pipe from a file or AI output
cat definition.json | casen generate bpmn --output order.bpmn

# Write to stdout
echo '{"id":"Defs","processes":[...]}' | casen generate bpmn --output -
```

### Print the JSON schema

Run `--help-schema` to print the full CompactDiagram reference — element types, event types,
field descriptions, and a worked example — formatted for quick AI consumption:

```sh
casen generate bpmn --help-schema
```

### CompactDiagram structure

```json
{
  "id": "Definitions_my-process",
  "processes": [{
    "id": "my-process",
    "name": "My Process",
    "elements": [
      { "id": "start",  "type": "startEvent",      "name": "Start" },
      { "id": "task1",  "type": "serviceTask",      "name": "Do Work", "jobType": "my-worker" },
      { "id": "gw",     "type": "exclusiveGateway", "name": "OK?" },
      { "id": "end-ok", "type": "endEvent",         "name": "Done" },
      { "id": "end-err","type": "endEvent",         "name": "Failed", "eventType": "error" }
    ],
    "flows": [
      { "id": "f1", "from": "start",  "to": "task1" },
      { "id": "f2", "from": "task1",  "to": "gw" },
      { "id": "f3", "from": "gw",     "to": "end-ok",  "condition": "= ok",      "name": "Yes" },
      { "id": "f4", "from": "gw",     "to": "end-err", "condition": "= not ok",  "name": "No" }
    ]
  }]
}
```

**Element types** — all 23 BPMN types supported:

- Tasks: `serviceTask` `userTask` `scriptTask` `businessRuleTask` `callActivity` `sendTask` `receiveTask` `manualTask` `task`
- Events: `startEvent` `endEvent` `intermediateCatchEvent` `intermediateThrowEvent` `boundaryEvent`
- Gateways: `exclusiveGateway` `parallelGateway` `inclusiveGateway` `eventBasedGateway` `complexGateway`
- Containers: `subProcess` `adHocSubProcess` `eventSubProcess` `transaction`

**Event types** (`eventType` field on event elements):
`timer` `message` `signal` `error` `escalation` `terminate` `cancel` `conditional` `link` `compensate`

**Zeebe extensions:**

| Field | Applies to | Effect |
|---|---|---|
| `jobType` | `serviceTask`, `sendTask` | Sets `zeebe:taskDefinition.type` |
| `taskHeaders` | `serviceTask`, `sendTask` | Sets `zeebe:taskHeaders` key/value pairs |
| `inputs` | any task | Sets `zeebe:ioMapping` inputs (target → source); connectors read their settings from these |
| `resultVariable` | `serviceTask`, `businessRuleTask` | Stores the result: a `resultVariable` task header for a Camunda connector (`io.camunda:…`), an output mapping of `response` for any other job worker |
| `modelerTemplate` | any element | `{ "id", "version" }` of the applied element template (`zeebe:modelerTemplate`) |
| `calledProcess` | `callActivity` | Sets `zeebe:calledElement.processId` |
| `formId` | `userTask` | Sets `zeebe:formDefinition.formId` |
| `decisionId` | `businessRuleTask` | Sets `zeebe:calledDecision.decisionId` |

**HTTP connector shorthand:**

```json
{
  "id": "http1",
  "type": "serviceTask",
  "name": "Call API",
  "jobType": "io.camunda:http-json:1",
  "inputs": {
    "url": "https://api.example.com/orders",
    "method": "POST"
  },
  "resultVariable": "apiResponse"
}
```

`authentication.type` defaults to `noAuth`. Older answers that put `url` and `method` in
`taskHeaders` still work: they are moved to input mappings, where the connector reads them.

## Modify-existing mode (`--input`)

Load an existing `.bpmn` file and patch it — add elements and flows, then re-apply auto-layout.
The default output overwrites the input file.

### Inspect the current state

Use `--dump-compact` to print the file's CompactDiagram JSON. Use this to discover existing
element IDs before writing a patch.

```sh
casen generate bpmn --input order.bpmn --dump-compact
```

Output is a `CompactDiagram` JSON object — the same format accepted by `--definition`.

### Add elements and flows

```sh
# Add a rejection path to an existing gateway with id "gw"
casen generate bpmn --input order.bpmn \
  --patch '{"elements":[
    {"id":"notify",     "type":"serviceTask","name":"Notify Customer","jobType":"notify-worker"},
    {"id":"end-reject", "type":"endEvent",   "name":"Rejected"}
  ],"flows":[
    {"id":"fn1","from":"gw",     "to":"notify",     "condition":"= not approved","name":"No"},
    {"id":"fn2","from":"notify", "to":"end-reject"}
  ]}'
```

Patch mode appends to the **first process** in the file. Flows in the patch can reference existing
element IDs — they are not required to be new.

### Pipe a patch from AI output

```sh
# AI generates the patch JSON, pipe it in
echo '{"elements":[...],"flows":[...]}' | casen generate bpmn --input order.bpmn
```

### Normalize layout

Run `--input` without `--patch` to re-apply auto-layout without changing the process model:

```sh
casen generate bpmn --input messy.bpmn --output clean.bpmn
```

### Flags for `--input` mode

| Flag | Description | Default |
|---|---|---|
| `--input` / `-f` | Existing `.bpmn` file to load | — |
| `--patch` | JSON patch: `{"elements":[...],"flows":[...]}` | — |
| `--dump-compact` | Print CompactDiagram JSON of `--input` and exit | — |
| `--output` / `-o` | Output path (`-` for stdout) | Overwrites `--input` file |

## Typical AI workflow

```sh
# 1. Inspect the existing file — AI learns element IDs
casen generate bpmn --input order.bpmn --dump-compact

# 2. Check the schema if needed
casen generate bpmn --help-schema

# 3. AI generates patch JSON and pipes it in
echo '{"elements":[...],"flows":[...]}' | casen generate bpmn --input order.bpmn

# 4. Verify the result
casen view bpmn order.bpmn
```

## Typed code generation (`casen generate types`)

`casen generate types` (or `casen gen types`) reads BPMN files and writes TypeScript types for the
job workers, message publishers and error throwers that run against them. A misspelt job type,
variable or error code then fails at compile time, not at runtime. The command lives under
`generate` because it produces a file from a model, like `generate bpmn` does.

```sh
# Files, directories (searched for .bpmn) and globs — quote globs to skip shell expansion
casen gen types processes/ --out src/generated/bpmn-types.ts
casen gen types "processes/**/*.bpmn" --out src/generated/bpmn-types.ts

# Print to stdout instead
casen gen types order.bpmn
```

The output is deterministic: everything is sorted, so the file only changes when the model does.
It starts with `// generated by casen gen types — do not edit`. It contains:

| Export | What it is |
|---|---|
| `processIds` / `ProcessId` | Executable process ids |
| `jobTypes` / `JobType` | Every static job type |
| `<Name>Variables`, `<Name>Output`, `<Name>Headers` | Each job type's variables, output and task headers |
| `JobTypes` | Job type → `{ variables, output, headers, errors, processIds, elementIds }` |
| `Messages`, `messageNames` / `MessageName` | Message names, with correlation key expressions |
| `signalNames` / `SignalName` | Signal names thrown or caught |
| `errorCodes` / `ErrorCode` | Error codes thrown or caught |
| `escalationCodes` / `EscalationCode` | Escalation codes thrown or caught |

See the [Typed workers guide](/docs/guides/typed-workers) for the typing rules and for how to use
the types with a worker.

### Keep the file current in CI

`--check` compares the generated source with the `--out` file and exits 1 when the file is missing or
out of date. It writes nothing.

```sh
casen gen types processes/ --out src/generated/bpmn-types.ts --check
```

### Check workers against the BPMN

`--check-workers <glob>` scans TypeScript and JavaScript sources for job worker registrations. It
reports job types that have no worker, and workers whose job type no BPMN element uses. Add
`--strict` to exit 1 when there is a mismatch.

```sh
casen gen types processes/ --check-workers "src/**/*.ts" --strict
casen gen types processes/ --check-workers src,workers --format json
```

The scan is a heuristic. It finds a job type only when it is a string literal in one of these forms:

| Pattern | Client |
|---|---|
| `createWorker("type", …)` | zeebe-node (legacy) |
| `taskType: "type"` | zeebe-node, `@camunda8/sdk` |
| `.createJobWorker({ jobType: "type", … })` (or `type:`) | `@camunda8/orchestration-cluster-api` |
| `registerJobWorker("type", …)` | custom registries |
| `.poll("type")` | `@bpmnkit/worker-client` |

A job type held in a variable or built with `${…}` is not found. Job types that start with
`io.camunda` belong to Camunda connectors. The connector runtime runs them, so they are never
reported as missing a worker.

### Flags

| Flag | Description | Default |
|---|---|---|
| `--out` | Write the generated source to this file (its directory is created) | stdout |
| `--check` | Exit 1 when `--out` is missing or stale; write nothing | — |
| `--check-workers` | Comma-separated globs or directories of worker sources to compare | — |
| `--strict` | With `--check-workers`: exit 1 on any mismatch | — |
| `--format` | `json` prints the `--check-workers` report as JSON | `text` |

---

### casen view

View BPMN, DMN, and Camunda form files in the browser via a local server.

Source: https://bpmnkit.com/docs/cli/view

`casen view` spawns a local HTTP server and opens the system browser to display BPMN diagrams,
DMN decision tables, and Camunda forms. All rendering happens server-side — no browser plugins required.

## Commands

```
casen view
├── open    — view any mix of .bpmn, .dmn, and .form files (auto-detects type)
├── bpmn    — view BPMN files rendered as SVG
├── dmn     — view DMN decision tables
└── form    — view Camunda form layouts
```

## Subcommands

### `casen view open`

Accepts any combination of `.bpmn`, `.dmn`, and `.form` files or directories. File type is
detected automatically from the extension.

```sh
# Mixed file types
casen view open order.bpmn routing.dmn review.form

# Entire project folder — all supported files get tabs
casen view open ./project/

# Mix files and folders
casen view open ./processes/ extra.dmn review.form
```

### `casen view bpmn`

Renders BPMN diagrams server-side as SVG using `exportSvg` from `@bpmnkit/core`.

```sh
# Single file
casen view bpmn process.bpmn

# All .bpmn files in a folder
casen view bpmn ./processes/

# Multiple specific files
casen view bpmn order.bpmn payment.bpmn shipping.bpmn
```

### `casen view dmn`

Renders DMN decision tables as ASCII art in a monospace panel.

```sh
casen view dmn eligibility.dmn
casen view dmn ./decisions/
```

### `casen view form`

Renders Camunda form layouts (`.form` files) as ASCII art in a monospace panel.

```sh
casen view form approval.form
casen view form ./forms/
```

## Folder support

Pass a directory instead of individual files. The viewer scans the top level of the directory
for files with the matching extension and gives each one its own tab.

```sh
# All .bpmn files in ./processes/
casen view bpmn ./processes/

# All supported types in ./project/
casen view open ./project/
```

## Flags

All subcommands accept the same flags:

| Flag | Description | Default |
|---|---|---|
| `--port` | Port for the local server | `3044` |
| `--theme` | Color theme: `light` or `dark` | `light` |
| `--no-open` | Do not open the browser automatically | `false` |

```sh
# Dark theme on a custom port without auto-opening
casen view bpmn process.bpmn --theme dark --port 8080 --no-open
```

## Tabbed navigation

When multiple files are loaded, the viewer renders a tab bar at the top. Click a tab to switch
diagrams. Tabs show the filename and are colour-coded by type (BPMN / DMN / Form).

## Stopping the server

Press `Ctrl+C` in the terminal where `casen view` is running. The server shuts down cleanly.

## Usage in an AI workflow

```sh
# Generate a process, then immediately view it
casen generate bpmn --template approval --process-id approve
casen view bpmn approve.bpmn

# Inspect a folder of processes together
casen view open ./processes/

# After patching an existing file, verify the result
casen generate bpmn --input order.bpmn --patch '...'
casen view bpmn order.bpmn --no-open --port 3044
```

---

### casen diff

Compare two BPMN files and report what a reviewer would see change — added, removed, changed and moved elements, as text or JSON, with an exit code for CI.

Source: https://bpmnkit.com/docs/cli/diff

`casen diff bpmn` answers the question a text diff cannot: *what changed about the process?*
Two files go in, and what comes out is the list of elements a reviewer would see differ —
named, not just identified.

```sh
casen diff bpmn old.bpmn new.bpmn
```

```
  + Notify Customer (Activity_1x8fj2)
  ~ Validate Order (Activity_0p2ktn)
  ⇄ Approved? (Gateway_09sd1a)

3 differences: 1 added, 1 changed, 1 moved
```

## Why the categories matter

| Marker | Category | Means |
| --- | --- | --- |
| `+` | added | Exists only in the later file |
| `−` | removed | Exists only in the earlier file |
| `~` | changed | Same element, different semantics — a task type, a condition, an extension |
| `⇄` | moved | Same semantics, different place on the canvas |

`moved` is the category that earns the command. The semantic hash behind
[`diffSemantics()`](/docs/packages/core#diffsemanticsbefore-after) deliberately drops all
diagram interchange — that is what makes it stable across a re-layout — so a task somebody
dragged reads there as no change at all. `casen diff` computes the layout half separately
from DI (bounds, waypoints, label placement, flags such as collapsed/expanded) and reports it
as its own category. An element that changed *and* moved is reported as changed, because a
semantic change is what a reviewer needs first.

Only elements a canvas could actually draw are counted, so a changed `targetNamespace` cannot
inflate the count against nothing on screen. When a diagram has more than one plane, the
per-plane totals are printed too — a change inside a collapsed sub-process is invisible in a
viewer until the reader drills into it.

## Flags

| Flag | Default | What it does |
| --- | --- | --- |
| `--format` | `text` | `text` or `json` |
| `--exit-code` | off | Exit non-zero when the two diagrams differ |
| `--ascii` | off | Also render both diagrams as ASCII art |

### As a pipeline gate

```sh
casen diff bpmn main/order.bpmn branch/order.bpmn --exit-code
```

Exits non-zero when anything differs, so a job can fail — or a review can be requested —
whenever a pull request touches the shape of a process rather than only its formatting.

### Machine-readable

```sh
casen diff bpmn old.bpmn new.bpmn --format json
```

```json
{
  "added": ["Activity_1x8fj2"],
  "removed": [],
  "changed": ["Activity_0p2ktn"],
  "moved": ["Gateway_09sd1a"],
  "total": 3,
  "planes": [{ "id": "order-process", "total": 3, "added": 1, "removed": 0, "changed": 1, "moved": 1 }]
}
```

### Alongside the picture

```sh
casen diff bpmn old.bpmn new.bpmn --ascii
```

Prints both diagrams as ASCII art above the summary — the same rendering
[`casen view`](/docs/cli/view) produces, and the same one the VS Code extension copies into a
pull request.

## The same diff elsewhere

The comparison itself is
[`diffDiagram()`](/docs/packages/core#diffdiagrambefore-after) in `@bpmnkit/core`, so every
surface shows the same answer:

- **Visually, in VS Code** — *Compare Diagram with HEAD*, or two selected files. See the
  [VS Code guide](/docs/guides/vscode).
- **On a share link** — `/drop/<before>/diff/<after>`. See the [Drop guide](/docs/guides/drop).
- **In your own canvas** — `createBpmnDiff()` from `@bpmnkit/plugins` returns a pair of
  plugins, one per canvas, with synchronised pan and zoom.

---

### casen connector

Browse the bundled Camunda 8 connector catalog, or generate connector element templates from OpenAPI specs, via the casen CLI.

Source: https://bpmnkit.com/docs/cli/connector

`casen connector` has two independent jobs: **browse** the bundled connector templates — Camunda 8's 133
out-of-the-box ones plus the few BPMN Kit maintains (`search`/`show` — used by the AI generation pipeline to wire a plan step to
a real service), and **generate** brand-new connector element templates from OpenAPI 3.x/Swagger
2.x specs (`generate`/`catalog` — for APIs Camunda doesn't ship a template for).

## Commands

```
casen connector
├── search      — find a bundled OOTB connector template by name/keyword
├── show        — show a bundled template's required/optional inputs
├── cards       — one card per operation: only the inputs it needs, for a request
├── api         — real endpoints of an HTTP API, from the offline API index, for the REST connector
├── generate    — generate new templates from an OpenAPI spec file or catalog entry
└── catalog     — list all built-in OpenAPI-catalog entries (for `generate`)
```

## Browse the bundled OOTB catalog

```sh
casen connector search slack
casen connector show io.camunda.connectors.Slack.v1
```

`search` scores the bundled templates by keyword match and prints a table (template id,
direction, task type, description). `show` prints a template's task type, direction, and its
required/optional input keys — these are the keys a `ProcessPlan` `connector` step's `values`
object uses (see [Building Processes with AI](/docs/guides/ai-implement)):

```
$ casen connector show io.camunda.connectors.Slack.v1
Slack connector  (io.camunda.connectors.Slack.v1)
Task type: io.camunda:slack:1
Direction: outbound
Create a channel or send a message to a channel or user

Required inputs:
  token (secret) — OAuth token
  data.channel — Channel/user name/email
  data.text — Message
  ...
```

A field marked `(secret)` should be supplied as a `{{secrets.NAME}}` placeholder, never a literal
credential. This is the same catalog `@bpmnkit/connectors`' `listConnectors()`/`searchConnectors()`
expose programmatically.

`show` lists every input of a template, whichever operation it belongs to: GitHub's lists `owner`
for each of its operations. `cards` answers a request with one card per operation instead, each with
only the inputs that operation uses, and the `values` that select it:

```
$ casen connector cards "create a github issue" --limit 1
github createIssue — GitHub Outbound Connector: Issues / Create an issue | owner* repo* issueTitle* | optional: authentication.pat(secret) githubBody issueAssignees(=FEEL) issueLabels(=FEEL) issueMilestone resultVariable resultExpressionCreateIssue(=FEEL) | authentication.authType=pat: pat | github_app
  values: {"operationGroup":"issues","issueOperationType":"createIssue"}
```

`*` marks a required input. A `mode=default: a | b(…)` part is a choice inside the operation, such
as an authentication type, with the required inputs each choice adds. Retries, timeouts, TLS and
other plumbing are left out unless you pass `--advanced`; `-o json` prints the cards as data.

## Endpoints of an HTTP API

Most systems have no dedicated connector, so the REST connector calls them. `api` prints the
real base URL, authentication and endpoints from the offline
[API index](/docs/packages/connector-gen#api-index). It searches the service the request names,
or the one `--service` gives:

```
$ casen connector api "refund a stripe payment" --limit 1
api stripe — Stripe API https://api.stripe.com auth=bearer secret=STRIPE_TOKEN
POST /v1/refunds — Create a refund | form body: amount currency charge customer expand instructions_email
```

Write the call as `with <id>: http POST /v1/refunds | api=stripe`. Applying the line adds the
base URL, the authentication with a secret placeholder, and the headers the endpoint needs.
`-o json` prints the endpoints as data.

## Generate from the OpenAPI catalog

The fastest way to get started. The catalog contains 30 popular APIs with pre-configured spec URLs
and auth defaults:

```sh
# List all available catalog entries
casen connector catalog

# Generate templates for the Stripe API
casen connector generate --api stripe --output ./templates/

# Generate templates for GitHub with a custom ID prefix
casen connector generate --api github --id-prefix com.myorg --output ./templates/
```

## Generate from a local file

Pass any local OpenAPI 3.x or Swagger 2.x file in YAML or JSON format:

```sh
casen connector generate --swagger ./openapi.yaml --output ./templates/

# JSON format works too
casen connector generate --swagger ./api-spec.json --output ./templates/
```

## All flags

| Flag | Description |
|---|---|
| `--swagger <file>` | Path to a local OpenAPI/Swagger YAML or JSON file |
| `--api <id>` | Catalog entry ID — downloads the spec automatically |
| `--output <dir>` | Directory to write `.json` template files into |
| `--base-url <url>` | Override the base URL from the spec |
| `--id-prefix <prefix>` | Reverse-DNS prefix for template IDs (e.g. `com.myorg`) |
| `--filter <regex>` | Filter operations by `operationId` or summary |
| `--expand-body` | Decompose top-level request body properties into individual input fields |
| `--auth <type>` | Pre-select auth type (see below) |
| `--format <fmt>` | `one-per-op` (default) or `array` — all templates in one file |
| `--dry-run` | Print generated templates to stdout instead of writing files |

### Auth types

| Value | Description |
|---|---|
| `noAuth` | No authentication fields |
| `apiKey` | Single API key field sent as a header |
| `basic` | Username + password (HTTP Basic) |
| `bearer` | Bearer token |
| `oauth-client-credentials-flow` | Client ID, secret, token URL, and scopes |

Auth is auto-detected from `components.securitySchemes` in the spec. Use `--auth` to override.

## Common workflows

### Preview before writing

Use `--dry-run` to inspect the generated JSON before committing to files:

```sh
casen connector generate --api resend --dry-run
```

### Filter to a subset of operations

Large APIs (GitHub, Stripe) produce hundreds of templates. Use `--filter` to narrow it down:

```sh
# Only generate templates for issue-related operations
casen connector generate --api github --filter "issues" --output ./templates/

# Only POST and PUT operations (filter on summary/operationId)
casen connector generate --api stripe --filter "create|update" --output ./templates/
```

### Expand request body fields

By default the request body is a single FEEL `Text` field. Use `--expand-body` to decompose
top-level properties into individual typed input fields — useful for simple, well-documented APIs:

```sh
casen connector generate --api resend --expand-body --output ./templates/
```

### All templates in one file

```sh
casen connector generate --api slack --format array --output ./templates/
# Writes: ./templates/slack.json  (array of all templates)
```

### Override the base URL

Useful when targeting a self-hosted or staging instance:

```sh
casen connector generate --swagger ./openapi.yaml \
  --base-url https://staging-api.mycompany.com \
  --output ./templates/
```

## What gets generated

Each operation in the spec becomes one Camunda element template JSON file. The template
pre-configures a `bpmn:ServiceTask` with job type `io.camunda:http-json:1` and wires up:

- **Method** and **URL** — hidden fixed fields; path parameters become FEEL expressions
  (e.g. `="https://api.example.com/users/"+userId`)
- **Path parameters** — individual `String` input fields
- **Query parameters** — mapped to a FEEL context object
- **Headers** — mapped to a FEEL context object
- **Request body** — single FEEL `Text` field, or individual typed fields with `--expand-body`
- **Authentication** — full 5-type auth block with visibility conditions; pre-selected to the
  detected or specified auth type
- **Output mapping**, **error expression**, **retries**, and **timeout** — standard connector fields

Import the generated `.json` files into Camunda Modeler via
**File → Import Element Templates** or by placing them in your `.camunda/element-templates/` directory.

## Built-in catalog

```sh
casen connector catalog
```

| ID | Name | Default auth |
|---|---|---|
| `github` | GitHub REST API | bearer |
| `cloudflare` | Cloudflare API | bearer |
| `stripe` | Stripe API | basic |
| `notion` | Notion API | bearer |
| `resend` | Resend Email API | bearer |
| `openai` | OpenAI API | bearer |
| `figma` | Figma API | bearer |
| `twilio` | Twilio Messaging API | basic |
| `slack` | Slack Web API | bearer |
| `jira` | Atlassian Jira API | bearer |
| `hubspot` | HubSpot CRM API | oauth-client-credentials-flow |
| `discord` | Discord API | bearer |
| `pagerduty` | PagerDuty API | apiKey |
| `zoom` | Zoom API | oauth-client-credentials-flow |
| `mailchimp` | Mailchimp API | apiKey |
| `asana` | Asana API | bearer |
| `sendgrid` | SendGrid Mail API | bearer |
| `paypal` | PayPal Payments API | oauth-client-credentials-flow |
| `plaid` | Plaid API | apiKey |
| `vercel` | Vercel API | bearer |
| `anthropic` | Anthropic API | apiKey |
| `shopify` | Shopify Admin API | bearer |
| `datadog` | Datadog API | apiKey |
| `sentry` | Sentry API | bearer |
| `intercom` | Intercom API | bearer |
| `contentful` | Contentful Management API | bearer |
| `airtable` | Airtable API | bearer |
| `twitch` | Twitch Helix API | oauth-client-credentials-flow |
| `klaviyo` | Klaviyo API | apiKey |
| `brex` | Brex API | oauth-client-credentials-flow |

## Programmatic usage

The underlying generator is available as a standalone package for use in Node.js scripts and build
pipelines. See [`@bpmnkit/connector-gen`](/docs/packages/connector-gen).

---

### AIKit Skills

Claude Code slash commands for AI-driven process implementation, review, testing, and deployment.

Source: https://bpmnkit.com/docs/cli/skills

`casen` ships four lightweight Claude Code slash commands that automate the process
development lifecycle — from natural language description to deployed, running process.
They drive `casen` directly (no MCP server, no proxy daemon).

For the full skill set — `/bpmnkit:implement`, `:extend`, `:agent`, `:connect`, plus generated
reference docs the skills read before authoring a plan — install the
[Claude Code plugin](/docs/guides/ai-implement#the-claude-code-plugin) instead.

## Installation

```sh
casen skills install
```

Copies the skill files into `.claude/commands/` in the current project directory.
Once installed, they appear in Claude Code's slash command picker.

```sh
# Reinstall or overwrite existing skills
casen skills install --force
```

---

## `/implement`

End-to-end process implementation from a natural language description.

```
/implement an invoice approval process for accounts payable
/implement employee onboarding with Okta provisioning and Jira ticket creation
/implement a supplier contract review workflow with DocuSign e-signature
```

**What it does:**

1. Resolves external interactions via `casen connector search`/`show`
2. Writes a `ProcessPlan` JSON file
3. Compiles it with `casen synth`, fixing any reported problems in the plan and retrying
4. Adds test scenarios and runs `casen test`
5. Scaffolds a worker stub for every job type with no existing worker or connector
6. Presents a summary and asks where to deploy

**Output:**
```
BPMN file: invoice-approval.bpmn

Connectors used: none
Workers: reused none / scaffolded workers/validate-invoice/, workers/trigger-payment/
Tests: 3/3 passed

Deploy to local Reebe, deploy to Camunda 8, or skip?
```

See [Building Processes with AI](/docs/guides/ai-implement) for a full walkthrough.

---

## `/review`

Run the full static analyzer on a BPMN file and get a structured findings report.

```
/review invoice-approval.bpmn
/review path/to/process.bpmn
```

**What it does:**

1. Runs `casen lint lint <file> --profile deploy` (the deploy-readiness gate) and the default profile (all categories)
2. Groups findings by severity: errors, warnings, info
3. Offers `casen lint lint <file> --fix` to apply auto-fixable findings
4. Ends with an explicit **"Deploy-ready: yes/no"** verdict

**Example output:**

```
Errors (1):
  - [Task_1] [deploy] Service task has no zeebe:taskDefinition type.

Warnings (2):
  - [Gateway_1] [pattern] Gateway has no default flow
  - [Process_1] [pattern] No timer event on long-running tasks

Deploy-ready: no — 1 error
```

---

## `/test`

Run scenario tests on a BPMN process and report path/branch coverage.

```
/test invoice-approval.bpmn
```

**What it does:**

1. Looks for the `<file>.bpmn.tests.json` sidecar (written automatically by `casen synth` from a plan's `tests` array); writes one if missing
2. Runs `casen test <file>.bpmn`
3. Cross-references gateway branches and error/timer boundaries against which scenarios exercise them
4. Reports pass/fail counts and any uncovered paths

**Example output:**

```
| Scenario | Result | Details |
|----------|--------|---------|
| happy-path | ✓ PASS | (12ms) |
| rejection-path | ✓ PASS | (9ms) |

Uncovered paths:
- Boundary "sla-timeout" (timer, 48h) has no test scenario

2/2 scenarios passed. 1 boundary uncovered.
```

---

## `/deploy`

Gate a BPMN process on deploy-readiness, then deploy it to local Reebe or Camunda 8.

```
/deploy invoice-approval.bpmn
```

**What it does:**

1. Runs `casen lint lint <file> --profile deploy` — stops if it reports any errors
2. Deploys via `casen deploy deploy <file>` (local) or `casen deploy deploy <file> --target camunda8`
3. Verifies with `casen process-definition list`
4. Reminds you to start any scaffolded workers and provision any `{{secrets.NAME}}` the process references

**Targets:**

- **Local Reebe** — deploys via `ZEEBE_ADDRESS` (default `http://localhost:26500`). Start Reebe first: `casen reebe start --port 26500`
- **Camunda 8** — deploys using the active `casen` profile. Set one up: `casen profile create`

---

## No MCP server required

These skills are plain Bash + Read/Write — they call `casen` directly and never depend on an MCP server or a running proxy. The `@bpmnkit/proxy` MCP server (`bpmn-aikit`) still exists separately, for Claude Desktop/Cursor or other MCP-only hosts — it's unrelated to these slash commands.

---

### casen Plugins

Official casen CLI plugins shipped with the BPMN Kit monorepo.

Source: https://bpmnkit.com/docs/cli/plugins

> **Auto-generated** — this page is built from `plugins-cli/*/package.json` during the site
> build. Do not edit it by hand.

Official plugins extend `casen` with domain-specific command groups. Install them with:

```sh
casen plugin install <name>
```

## Available Plugins

| Plugin | Description |
|--------|-------------|
| [`@bpmnkit/casen-report`](#-bpmnkit-casen-report) | Render HTML reports from Camunda 8 incident and SLA data |
| [`@bpmnkit/casen-worker-ai`](#-bpmnkit-casen-worker-ai) | AI task worker plugin for casen — classify, summarize, extract, and decide using Claude |
| [`@bpmnkit/casen-worker-http`](#-bpmnkit-casen-worker-http) | Example casen worker plugin — processes HTTP connector jobs using the JSONPlaceholder API |

---

## `@bpmnkit/casen-report`

Render HTML reports from Camunda 8 incident and SLA data

### Installation

```sh
casen plugin install @bpmnkit/casen-report
```

| Command | Description |
|---------|-------------|
| `casen report incidents` | Generate an HTML report of current incidents grouped by process |
| `casen report sla` | Generate an SLA compliance report for process instances |

---

## `@bpmnkit/casen-worker-ai`

AI task worker plugin for casen — classify, summarize, extract, and decide using Claude

### Installation

```sh
casen plugin install @bpmnkit/casen-worker-ai
```

| Command | Description |
|---------|-------------|
| `casen ai-worker classify` | Classify text into one of the given categories |
| `casen ai-worker summarize` | Summarize text to a given length and style |
| `casen ai-worker extract` | Extract structured fields from unstructured text |
| `casen ai-worker decide` | Make a boolean decision based on a question, context, and optional policy |

---

## `@bpmnkit/casen-worker-http`

Example casen worker plugin — processes HTTP connector jobs using the JSONPlaceholder API

### Installation

```sh
casen plugin install @bpmnkit/casen-worker-http
```

| Command | Description |
|---------|-------------|
| `casen http-worker start` | Subscribe to HTTP connector jobs and complete them with live API data |

---

## Authoring Plugins

See the [Plugin Authoring](/docs/cli/plugin-authoring) guide to build and publish your own `casen` plugin.

---

### casen Plugin Authoring

Build and publish plugins that extend the casen CLI with new command groups.

Source: https://bpmnkit.com/docs/cli/plugin-authoring

casen plugins are ordinary npm packages that export a `CasenPlugin` object. Once installed, their
commands appear in the main TUI and in shell tab-completion alongside the built-in ones.

## Scaffold a new plugin

The fastest way to start is with the official scaffolding tool:

```sh
pnpm create @bpmnkit/casen-plugin
# or: npx @bpmnkit/create-casen-plugin
# or: bunx @bpmnkit/create-casen-plugin
```

The tool runs interactively:

```
  @bpmnkit/create-casen-plugin — casen plugin scaffolding

  Plugin name (npm package name): casen-deploy
  Display name             (Deploy):
  Description              (): Git-tag-aware deploys for casen
  Author                   (): acme

  Initialize git repo? (Y/n): Y

  ✓ package.json
  ✓ tsconfig.json
  ✓ src/index.ts
  ✓ .gitignore
  ✓ git init

  Done! Created casen-deploy at ./casen-deploy
```

### Non-interactive mode

Pass flags to skip all prompts — useful in CI or cookiecutter scripts:

```sh
pnpm create @bpmnkit/casen-plugin \
  --name casen-deploy \
  --description "Git-tag-aware deploys for casen" \
  --author acme \
  --no-git
```

| Flag | Description |
|---|---|
| `--name` / `-n` | npm package name (first positional arg also works) |
| `--display-name` | Human-readable name shown in `casen plugin list` |
| `--description` / `-d` | One-line description |
| `--author` / `-a` | Author name or npm username |
| `--no-git` | Skip `git init` |

## What gets generated

```
casen-deploy/
├── package.json       # "casen-plugin" keyword pre-set; no manual step needed
├── tsconfig.json      # standalone, no monorepo dependency
├── .gitignore
└── src/
    └── index.ts       # CasenPlugin default export with an example command
```

### Generated `package.json`

```json
{
  "name": "casen-deploy",
  "version": "0.1.0",
  "description": "Git-tag-aware deploys for casen",
  "type": "module",
  "main": "dist/index.js",
  "keywords": ["casen-plugin"],
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "prepublishOnly": "tsc"
  },
  "devDependencies": {
    "@bpmnkit/cli-sdk": "latest",
    "typescript": "latest"
  }
}
```

The `"casen-plugin"` keyword is injected automatically — it is how `casen plugin search` discovers
your package on npm once published.

### Generated `src/index.ts`

```typescript
import type { CasenPlugin } from "@bpmnkit/cli-sdk"

const plugin: CasenPlugin = {
  id: "com.acme.casen-deploy",
  name: "Deploy",
  version: "0.1.0",
  groups: [
    {
      name: "deploy",
      description: "Deploy commands",
      commands: [
        {
          name: "hello",
          description: "Example command — replace with your own",
          async run(ctx) {
            ctx.output.ok("Hello from Deploy!")
          },
        },
      ],
    },
  ],
}

export default plugin
```

Replace the example command with your own logic. Add as many command groups and commands as needed.

## The `@bpmnkit/cli-sdk` SDK

Install the SDK as a devDependency in your plugin:

```sh
pnpm add -D @bpmnkit/cli-sdk
```

It exports all types you need — no runtime dependency on casen internals.

### `CasenPlugin`

The root export. Default-export one instance of this from `dist/index.js`:

```typescript
interface CasenPlugin {
  id: string          // reverse-domain ID, e.g. "com.acme.casen-deploy"
  name: string        // shown in "casen plugin list"
  version: string
  groups: CommandGroup[]
}
```

### `CommandGroup`

Maps to one top-level token in the CLI (`casen <group>`). The name must be unique across all
installed plugins and the casen core commands:

```typescript
interface CommandGroup {
  name: string        // kebab-case, e.g. "deploy"
  aliases?: string[]
  description: string
  commands: Command[]
}
```

### `Command`

A single executable action within a group (`casen <group> <command>`):

```typescript
interface Command {
  name: string
  aliases?: string[]
  description: string
  args?: ArgSpec[]
  flags?: FlagSpec[]
  examples?: Example[]
  run(ctx: RunContext): Promise<void>
}
```

### `RunContext`

Passed to every `run()` function. Use it to read arguments, write output, and access
authenticated Camunda clients:

```typescript
interface RunContext {
  positional: string[]          // positional args after <group> <command>
  flags: ParsedFlags            // { flagName: value }
  output: OutputWriter          // table / json / yaml renderer
  getClient(): Promise<unknown>       // Camunda C8 REST client
  getAdminClient(): Promise<unknown>  // Camunda Admin API client
}
```

### `OutputWriter`

Use `ctx.output` for all output so the `--output` flag (table / json / yaml) is respected:

```typescript
ctx.output.ok("Done.")                          // ✓ Done.
ctx.output.info("Deploying…")                   // → Deploying…
ctx.output.printList({ items }, columns)        // table of rows
ctx.output.printItem(singleObject)              // key-value pairs
ctx.output.print(anything)                      // raw, format-aware
```

## Writing commands

### Positional arguments

```typescript
{
  name: "release",
  description: "Tag and deploy the current process version",
  args: [
    { name: "process-id", description: "BPMN process ID", required: true },
    { name: "tag",        description: "Release tag, e.g. v1.2.0",   required: true },
  ],
  async run(ctx) {
    const processId = ctx.positional[0]
    const tag = ctx.positional[1]
    if (!processId || !tag) throw new Error("Missing required arguments")
    // ...
  },
}
```

### Flags

```typescript
{
  name: "release",
  flags: [
    {
      name: "dry-run",
      short: "n",
      description: "Show what would happen without making changes",
      type: "boolean",
      default: false,
    },
    {
      name: "env",
      description: "Target environment",
      type: "string",
      default: "production",
      enum: ["staging", "production"],
    },
  ],
  async run(ctx) {
    const dryRun = ctx.flags["dry-run"] === true
    const env = ctx.flags.env as string
    // ...
  },
}
```

### Calling the Camunda API

Cast `getClient()` to `CamundaClient` from `@bpmnkit/api` if you need full type coverage,
or access it generically via the unknown type:

```typescript
import type { CamundaClient } from "@bpmnkit/api"

async run(ctx) {
  const client = await ctx.getClient() as CamundaClient
  const { items } = await client.processDefinition.searchProcessDefinitions({})
  ctx.output.printList({ items }, [
    { key: "bpmnProcessId", header: "PROCESS ID" },
    { key: "name",          header: "NAME" },
    { key: "version",       header: "VER" },
  ])
},
```

### Throwing errors

Throw a plain `Error` for user-facing errors. casen catches it, prints `error: <message>` to
stderr, and exits with code 1:

```typescript
async run(ctx) {
  const name = ctx.positional[0]
  if (!name) throw new Error("Missing required argument: <name>")
  // ...
}
```

## Test locally

Build and install your plugin from the local directory:

```sh
cd casen-deploy
pnpm install
pnpm build

casen plugin install ./casen-deploy
```

Restart casen. Your commands appear under `casen deploy` (or whatever group name you chose).

To uninstall during development:

```sh
casen plugin remove casen-deploy
```

## Publish to npm

When you're ready to share:

```sh
cd casen-deploy
npm publish
```

The `prepublishOnly` script in the generated `package.json` runs `tsc` automatically before
publishing, so `dist/` is always up to date.

Because `"casen-plugin"` is in `keywords`, your package is immediately discoverable via:

```sh
casen plugin search deploy
```

## Plugin naming conventions

| Convention | Reason |
|---|---|
| Name packages `casen-<feature>` | Predictable, easy to search |
| Set `id` to a reverse-domain string | Avoids conflicts across organisations |
| Keep each group name unique | casen merges all groups into one flat namespace |
| Prefix group name with your org for internal plugins | e.g. `acme-deploy` avoids clashing with a published `casen-deploy` |

---

### casen dev

One command for the local development loop — edit every process in a folder in the browser, simulate it, and re-run lint and scenario tests on every save. No Docker, no cluster, no licence key.

Source: https://bpmnkit.com/docs/cli/dev

`casen dev` turns a folder of `.bpmn`, `.dmn` and `.form` files into a local development
environment. It starts a small web server, opens the BPMN Kit editor in your browser, and
re-checks each file every time it changes — whether you saved it in the browser or in another
editor.

```sh
casen dev              # the current folder
casen dev ./processes  # another folder
```

```
  casen dev  /home/me/shop
  UI        http://127.0.0.1:4747/
  files     3 (2 bpmn, 1 dmn, 0 form)
  scenarios @bpmnkit/engine

✖ orders/order.bpmn  lint 0✖ 2⚠  tests 1/2
    FAIL out of stock
      variables.inStock: expected false, got true
✓ orders/refund.bpmn  lint 0✖ 0⚠
✓ risk-score.dmn
  3 files · 1 failing: orders/order.bpmn
  Watching for changes. Ctrl+C to stop.
```

## What you get

- **A file list.** Every `.bpmn`, `.dmn` and `.form` file under the folder, with a green or red
  mark for its last check. Hidden directories, `node_modules`, `dist`, `build`, `target`,
  `coverage` and `out` are skipped.
- **The editor.** BPMN opens in the full diagram editor with in-canvas lint markers; DMN in the
  decision editor; forms in the form editor.
- **Simulation.** The Play button runs the diagram in the browser on `@bpmnkit/engine`, with
  tokens drawn on the elements they sit on. DMN files in the same folder are deployed with it,
  so business rule tasks evaluate.
- **Saving back to disk.** Edits are written about half a second after you stop, or at once with
  <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>S</kbd>. Each save is written into the file that is
  already there, keeping its indentation, attribute order and comments, and is only used if it
  reads back as the same model — the same writer as the [VS Code extension](/docs/guides/vscode),
  so moving a box changes the lines for that box, not the whole file.
- **Live reload.** Change a file anywhere else — your text editor, `git checkout`, a code
  generator — and the open diagram reloads. If you have unsaved edits in the browser at the same
  time, nothing is thrown away: you choose between reloading and overwriting.
- **Checks on every change.** Each changed BPMN file is linted exactly as
  `casen lint` would lint it (including a project `.bpmnlintrc`, and connector inputs checked
  against the element templates from the file's folder up to the served folder — see
  [workspace templates](/docs/packages/connectors#workspace-templates)), and the
  scenarios in its `<file>.bpmn.tests.json` sidecar are run as `casen test` runs them. Changing a
  `.dmn` file re-runs the scenarios of the processes beside it. Results appear in the browser's
  Checks panel and in the terminal.
- **Tests you can edit.** The Tests tab of Play mode reads and writes the same
  `.bpmn.tests.json` sidecar, so scenarios written in the browser are the ones `casen test` runs
  in CI.

## Flags

| Flag | Default | What it does |
| --- | --- | --- |
| `--port <n>` | `4747`, or the next free port | Port to listen on. An explicit port that is taken is an error. |
| `--no-open` | opens the browser | Print the URL without opening a browser. |
| `--engine ts\|wasm` | `ts` | Engine for the scenario runs after each save. `wasm` runs them on Reebe compiled to WebAssembly, for Zeebe semantics — the engine `casen test` uses. Simulation in the browser always uses `@bpmnkit/engine`. |

## Deploying and AI

`casen dev` does not start the AI bridge or connect to a cluster. For those, run the proxy
alongside it:

```sh
casen proxy start   # port 3033: AI bridge, Camunda API proxy, run history
casen deploy ...    # deploy what you built
```

## Security

The server only listens on `127.0.0.1`. It answers only requests addressed to a loopback host
name, which stops DNS-rebinding pages, and every API call needs a random token that exists only
inside the page it served, so other sites open in the same browser cannot read or write your
files. Reads and writes are limited to `.bpmn`, `.dmn`, `.form` and `.bpmn.tests.json` files
inside the project folder: paths that climb out of it, hidden paths and symlinks pointing
outside it are refused. Nothing is ever executed on your behalf.

---

### casen migrate

Convert Camunda 7 BPMN models to Camunda 8 and get a per-element report of what was converted, what needs a person, and what Camunda 8 cannot do — as text or JSON, with a CI gate.

Source: https://bpmnkit.com/docs/cli/migrate

`casen migrate c7` converts Camunda 7 models to Camunda 8. It rewrites what it can rewrite
mechanically and reports every Camunda 7 construct it finds, one line per element. The
[migration guide](/docs/guides/migrate-from-camunda-7) explains what is converted and why.

```sh
casen migrate c7 order.bpmn
```

```
order.bpmn → order.c8.bpmn
  19 convertible · 8 manual · 2 unsupported

  UNSUPPORTED
    order-fulfillment  camunda:historyTimeToLive
      Camunda 8 has no per-process history time to live (was "180").
      → Configure data retention for the cluster (Operate, Tasklist and Optimize archiving).
    …
  MANUAL
    Task_ship  camunda:class
      Java delegate class "com.acme.orders.ShipOrderDelegate" runs inside the Camunda 7 engine; …
      → Implement a job worker for type "shipOrderDelegate" …
    …
  CONVERTIBLE
    Task_charge  camunda:type=external
      External task topic "charge-payment" became job type "charge-payment".
    …
```

The groups come in order of work: `unsupported` (Camunda 8 has no equivalent), `manual`
(Camunda 8 has one, but a person must write or check it), `convertible` (done).

## Where the output goes

- By default, each `name.bpmn` is written to `name.c8.bpmn` beside it. The Camunda 7 file is
  never changed.
- With `--out <dir>`, files are written to that directory under their own names. The
  directory is created if it does not exist.
- An existing output file is never overwritten unless you pass `--force`. The command
  reports the file and exits 1.

The output keeps the source file's formatting and element order, so a text diff against the
Camunda 7 file shows only what the migration changed.

## Flags

| Flag | Default | What it does |
| --- | --- | --- |
| `--out <dir>` | beside the input | Write converted files to this directory |
| `--check` | off | Report only. Write nothing, and exit 1 if any `manual` or `unsupported` finding remains |
| `--format` | `text` | `text` or `json` |
| `--force` | off | Overwrite converted files that already exist |

Put the flags after the file names: `casen migrate c7 models/*.bpmn --check`.

### As a pipeline gate

```sh
casen migrate c7 models/*.bpmn --check --format json
```

The JSON is an array with one entry per file: `file`, `output` (`null` with `--check`),
`counts`, and `findings`. Each finding has `elementId`, `elementType`, `processId`,
`construct`, `severity`, `message`, `suggestion`, and `applied`. `applied` tells you if the
converter wrote a Camunda 8 equivalent. A file that already targets Camunda 8, or that cannot
be read, is reported with an `error` and makes the command exit 1.

---

## Links

- Live Editor: https://bpmnkit.com/editor
- Documentation: https://bpmnkit.com/docs
- GitHub: https://github.com/bpmnkit/bpmnkit
- npm: https://www.npmjs.com/org/bpmnkit
- Compact index (llms.txt): https://bpmnkit.com/llms.txt