@bpmnkit/docspack 0.0.1

package/.llms/chunks/guides.patterns.pattern-schema.md

@@ -0,0 +1,38 @@
+# Pattern Library — 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.
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/

package/.llms/chunks/guides.patterns.see-also.md

@@ -0,0 +1,7 @@
+# Pattern Library — See also
+
+- [Building Processes with AI](/guides/ai-implement/) — how Claude uses patterns during `/bpmnkit:implement`
+- [`@bpmnkit/patterns` source](https://github.com/bpmnkit/monorepo/tree/main/packages/patterns)
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/

package/.llms/chunks/guides.patterns.using-patterns-from-the-cli.md

@@ -0,0 +1,30 @@
+# Pattern Library — Using patterns from the CLI
+
+```sh
+casen pattern list
+casen pattern get invoice-approval
+casen pattern get "employee onboarding workflow"   # free-text match
+```
+
+
+## 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))
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/

package/.llms/chunks/guides.patterns.what-a-pattern-contains.md

@@ -0,0 +1,18 @@
+# Pattern Library — 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.
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/

package/.llms/chunks/guides.simulation.dmn-decision-evaluation.md

@@ -0,0 +1,51 @@
+# Simulation — 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");
+  });
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/simulation/

package/.llms/chunks/guides.simulation.instance-state.md

@@ -0,0 +1,29 @@
+# Simulation — 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
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/simulation/

package/.llms/chunks/guides.simulation.md

@@ -0,0 +1,51 @@
+# 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,
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/simulation/

package/.llms/chunks/guides.simulation.message-correlation.md

@@ -0,0 +1,30 @@
+# Simulation — 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
+  },
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/simulation/

package/.llms/chunks/guides.simulation.multiple-deployments.md

@@ -0,0 +1,14 @@
+# Simulation — 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: "..." }]
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/simulation/

package/.llms/chunks/guides.workers-standalone.anatomy-of-a-worker.md

@@ -0,0 +1,42 @@
+# Standalone Workers — 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}`)
+  }
+}
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/guides.workers-standalone.camunda-saas.md

@@ -0,0 +1,43 @@
+# Standalone Workers — 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 |
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/guides.workers-standalone.environment-variables.md

@@ -0,0 +1,14 @@
+# Standalone Workers — 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).
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/guides.workers-standalone.md

@@ -0,0 +1,35 @@
+# Standalone Workers
+
+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
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/guides.workers-standalone.running-workers.md

@@ -0,0 +1,61 @@
+# Standalone Workers — 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
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/guides.workers-standalone.see-also.md

@@ -0,0 +1,7 @@
+# Standalone Workers — See also
+
+- [`@bpmnkit/worker-client`](/packages/worker-client/) — full API reference
+- [AI-Driven Implementation](/guides/ai-implement/) — scaffold workers as part of `/implement`
+
+---
+Source: https://docs.bpmnkit.com/guides/workers-standalone/

package/.llms/chunks/packages.api.incident-resolution.md

@@ -0,0 +1,31 @@
+# @bpmnkit/api — 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
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/api/

package/.llms/chunks/packages.api.observability-events.md

@@ -0,0 +1,13 @@
+# @bpmnkit/api — 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})`));
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/api/

package/.llms/chunks/packages.api.overview.md

@@ -0,0 +1,49 @@
+# @bpmnkit/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,
+  },
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/api/

package/.llms/chunks/packages.api.process-operations.md

@@ -0,0 +1,60 @@
+# @bpmnkit/api — 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();
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/api/

package/.llms/chunks/packages.api.resource-namespaces.md

@@ -0,0 +1,20 @@
+# @bpmnkit/api — 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 |
+
+---
+Source: https://docs.bpmnkit.com/packages/api/