@bpmnkit/docspack 0.0.1

package/.llms/chunks/packages.docspack.reading-it-yourself.md

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

package/.llms/chunks/packages.docspack.trust.md

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

package/.llms/chunks/packages.docspack.using-the-index-directly.md

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

package/.llms/chunks/packages.editor.basic-setup.md

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

package/.llms/chunks/packages.editor.full-editor-with-all-plugins.md

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

package/.llms/chunks/packages.editor.hud-options.md

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

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

@@ -0,0 +1,21 @@
+# @bpmnkit/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
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/editor/

package/.llms/chunks/packages.engine.installation.md

@@ -0,0 +1,77 @@
+# @bpmnkit/engine — 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.getDeployedProcesses()`
+
+Returns metadata about all deployed process definitions:
+
+```typescript
+const processes = engine.getDeployedProcesses();
+// [{ id: "my-process", name: "My Process", version: 1 }]
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/engine/

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

@@ -0,0 +1,19 @@
+# @bpmnkit/engine — Overview
+
+`@bpmnkit/engine` is a lightweight BPMN 2.0 process engine that runs entirely in the
+JavaScript runtime — no external services required.
+
+**Supported BPMN elements:**
+- Service tasks, user tasks, script tasks, manual tasks
+- Exclusive, parallel, inclusive, and event-based gateways
+- Timer events (ISO 8601 duration, date, and cycle)
+- Message correlation (intermediate catch events, message start)
+- DMN decision evaluation (requires `@bpmnkit/core`)
+- Boundary events (timer, error, message)
+- Call activities (inline subprocess invocation)
+- IO variable mappings (Zeebe `zeebe:ioMapping` extension)
+
+Zero runtime dependencies. ESM-only.
+
+---
+Source: https://docs.bpmnkit.com/packages/engine/

package/.llms/chunks/packages.engine.processinstance.md

@@ -0,0 +1,17 @@
+# @bpmnkit/engine — ProcessInstance
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `"running" \| "completed" \| "cancelled"` | Current lifecycle state |
+| `activeElements` | `Set<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?)` | Correlate a message to a waiting event |
+
+---
+Source: https://docs.bpmnkit.com/packages/engine/

package/.llms/chunks/packages.engine.variable-scoping.md

@@ -0,0 +1,27 @@
+# @bpmnkit/engine — Variable Scoping
+
+Variables follow hierarchical scope rules:
+
+- Global variables are set at the process level
+- Sub-processes and call activities create child scopes
+- IO mappings move data between scopes on task entry/exit
+- `setLocal` writes to the innermost scope only
+
+
+## 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.
+
+---
+Source: https://docs.bpmnkit.com/packages/engine/

package/.llms/chunks/packages.worker-client.client.poll-jobtype-options.md

@@ -0,0 +1,40 @@
+# @bpmnkit/worker-client — `client.poll(jobType, options?)`
+
+Async generator. Continuously polls Zeebe for jobs of the given type. Pauses 5 seconds
+between polls when no jobs are available.
+
+```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 |
+
+### 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>
+}
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/worker-client/

package/.llms/chunks/packages.worker-client.createworkerclient-options.md

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

package/.llms/chunks/packages.worker-client.job.complete-variables.md

@@ -0,0 +1,29 @@
+# @bpmnkit/worker-client — `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. Zeebe will retry (or raise an incident if retries reach zero).
+`retries` defaults to `0` if not provided — pass `job.retries - 1` to decrement.
+
+```typescript
+await job.fail("External API returned 503", job.retries - 1)
+```
+
+
+## `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" })
+```
+
+---
+Source: https://docs.bpmnkit.com/packages/worker-client/

package/.llms/chunks/packages.worker-client.md

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

package/.llms/chunks/packages.worker-client.oauth2-camunda-saas.md

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

package/.llms/chunks/packages.worker-client.see-also.md

@@ -0,0 +1,7 @@
+# @bpmnkit/worker-client — See also
+
+- [Standalone Workers](/guides/workers-standalone/) — scaffolding, running, and deploying workers
+- [AI-Driven Implementation](/guides/ai-implement/) — generate workers automatically with `/implement`
+
+---
+Source: https://docs.bpmnkit.com/packages/worker-client/