@bpmnkit/docspack 0.0.1

package/.llms/chunks/cli.skills.review.md

@@ -0,0 +1,33 @@
+# AIKit Skills — `/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
+```
+
+---
+
+---
+Source: https://docs.bpmnkit.com/cli/skills/

package/.llms/chunks/cli.skills.test.md

@@ -0,0 +1,33 @@
+# AIKit Skills — `/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.
+```
+
+---
+
+---
+Source: https://docs.bpmnkit.com/cli/skills/

package/.llms/chunks/cli.view.folder-support.md

@@ -0,0 +1,31 @@
+# casen view — 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
+```
+
+---
+Source: https://docs.bpmnkit.com/cli/view/

package/.llms/chunks/cli.view.md

@@ -0,0 +1,70 @@
+# casen 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/
+```
+
+---
+Source: https://docs.bpmnkit.com/cli/view/

package/.llms/chunks/cli.view.tabbed-navigation.md

@@ -0,0 +1,28 @@
+# casen view — 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
+```
+
+---
+Source: https://docs.bpmnkit.com/cli/view/

package/.llms/chunks/getting-started.concepts.ai-compact-format.md

@@ -0,0 +1,23 @@
+# Core Concepts — 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
+- Zeebe extensions (task type, IO mappings, headers) are inlined
+- The full diagram of a typical approval workflow fits in ~500 tokens
+
+---
+Source: https://docs.bpmnkit.com/getting-started/concepts/

package/.llms/chunks/getting-started.concepts.auto-layout.md

@@ -0,0 +1,24 @@
+# Core Concepts — 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.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/concepts/

package/.llms/chunks/getting-started.concepts.parsing-and-serializing.md

@@ -0,0 +1,26 @@
+# Core Concepts — Parsing and Serializing
+
+The SDK can round-trip any BPMN 2.0 XML — parse it, modify it in TypeScript, and export it back:
+
+```typescript
+import { Bpmn } from "@bpmnkit/core";
+
+// Parse XML into a typed object
+const definitions = Bpmn.parse(xmlString);
+
+// Access the first process
+const process = definitions.rootElements.find(
+  (el) => el.$type === "bpmn:Process"
+);
+
+// Export back to XML
+const newXml = Bpmn.export(definitions);
+```
+
+### Round-trip fidelity
+
+The parser preserves all attributes, extensions, and vendor-specific elements. Exporting the
+parsed object produces XML that is semantically equivalent to the input.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/concepts/

package/.llms/chunks/getting-started.concepts.the-fluent-builder.md

@@ -0,0 +1,41 @@
+# Core 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.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/concepts/

package/.llms/chunks/getting-started.concepts.zeebe-extensions.md

@@ -0,0 +1,25 @@
+# Core Concepts — 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" },
+  ],
+})
+```
+
+---
+Source: https://docs.bpmnkit.com/getting-started/concepts/

package/.llms/chunks/getting-started.installation.md

@@ -0,0 +1,38 @@
+# 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
+```
+
+---
+Source: https://docs.bpmnkit.com/getting-started/installation/

package/.llms/chunks/getting-started.installation.runtime-requirements.md

@@ -0,0 +1,13 @@
+# Installation — 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.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/installation/

package/.llms/chunks/getting-started.installation.svg-canvas-viewer.md

@@ -0,0 +1,41 @@
+# Installation — 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](/guides/ai-implement/) for a full walkthrough.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/installation/

package/.llms/chunks/getting-started.installation.worker-client.md

@@ -0,0 +1,40 @@
+# Installation — 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"
+  }
+}
+```
+
+---
+Source: https://docs.bpmnkit.com/getting-started/installation/

package/.llms/chunks/getting-started.quick-start.md

@@ -0,0 +1,31 @@
+# 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.
+
+---
+Source: https://docs.bpmnkit.com/getting-started/quick-start/

package/.llms/chunks/getting-started.quick-start.step-2-simulate-locally.md

@@ -0,0 +1,28 @@
+# Quick Start — 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();
+  });
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/getting-started/quick-start/

package/.llms/chunks/getting-started.quick-start.step-3-deploy-to-camunda-8.md

@@ -0,0 +1,33 @@
+# Quick Start — 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);
+```
+
+---
+Source: https://docs.bpmnkit.com/getting-started/quick-start/

package/.llms/chunks/getting-started.quick-start.what-s-next.md

@@ -0,0 +1,14 @@
+# Quick Start — What's next?
+
+- [AI-Driven Implementation](/guides/ai-implement/) — let Claude implement processes end-to-end from a description
+- [Core Concepts](/getting-started/concepts/) — understand how the builder, layout, and roundtrip work
+- [Building Processes](/guides/building-processes/) — tasks, events, sub-processes, and markers
+- [Gateways & Branching](/guides/gateways/) — exclusive, parallel, and event-based gateways
+
+:::tip[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.
+:::
+
+---
+Source: https://docs.bpmnkit.com/getting-started/quick-start/

package/.llms/chunks/guides.ai-agents.deploy-grade-validation.md

@@ -0,0 +1,19 @@
+# AI Agents — 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.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/

package/.llms/chunks/guides.ai-agents.how-it-s-modeled.md

@@ -0,0 +1,11 @@
+# AI Agents — 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.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/

package/.llms/chunks/guides.ai-agents.md

@@ -0,0 +1,18 @@
+# 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`.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/

package/.llms/chunks/guides.ai-agents.see-also.md

@@ -0,0 +1,7 @@
+# AI Agents — See also
+
+- [Building Processes with AI](/guides/ai-implement/) — the overall plan/synth pipeline
+- [`casen connector`](/cli/connector/) — searching the catalog for connector-backed tools
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/

package/.llms/chunks/guides.ai-agents.testing-without-a-real-llm-call.md

@@ -0,0 +1,26 @@
+# AI Agents — 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`.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/