@bpmnkit/docspack 0.0.6 → 1.0.0

package/.llms/chunks/getting-started.stability.deprecation.md

@@ -0,0 +1,15 @@
+# Stability and Versioning — 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`.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.support-window.md

@@ -0,0 +1,49 @@
+# Stability and Versioning — 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/monorepo/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 fourteen published packages stay on 0.x on purpose, and make no 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/monorepo/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.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.versions-are-per-package-not-per-repo.md

@@ -0,0 +1,17 @@
+# Stability and Versioning — 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`.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.what-counts-as-public-api.md

@@ -0,0 +1,33 @@
+# Stability and Versioning — 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.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.what-is-a-breaking-change.md

@@ -0,0 +1,70 @@
+# Stability and Versioning — 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.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.what-is-not-a-breaking-change.md

@@ -0,0 +1,25 @@
+# Stability and Versioning — 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**.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/getting-started.stability.what-this-page-is-for.md

@@ -0,0 +1,21 @@
+# Stability and Versioning — 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.
+
+---
+Source: https://bpmnkit.com/docs/getting-started/stability

package/.llms/chunks/guides.ai.previewing-while-the-model-writes.md

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

package/.llms/chunks/packages.ascii.from-the-command-line.md

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

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

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

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

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

package/.llms/chunks/packages.ascii.rendering-a-decision-table.md

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

package/.llms/chunks/packages.ascii.rendering-a-form.md

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

package/.llms/chunks/packages.connectors.api-reference.md

@@ -0,0 +1,22 @@
+# @bpmnkit/connectors — 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 |
+| `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 116 bundled templates, raw |
+
+From `@bpmnkit/connectors/node`: `discoverElementTemplates`, `collectElementTemplates`,
+`DEFAULT_CONFIG_FOLDER`, `TEMPLATES_SUBFOLDER`.
+
+---
+Source: https://bpmnkit.com/docs/packages/connectors

package/.llms/chunks/packages.connectors.applying-a-template.md

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

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

@@ -0,0 +1,45 @@
+# @bpmnkit/connectors — Installation
+
+```sh
+npm install @bpmnkit/connectors
+```
+
+
+## Browsing the catalog
+
+```typescript
+import { listConnectors, searchConnectors, getTemplate } from "@bpmnkit/connectors";
+
+listConnectors().length;        // 116
+searchConnectors("slack");      // 6 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.
+
+---
+Source: https://bpmnkit.com/docs/packages/connectors

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

@@ -0,0 +1,16 @@
+# @bpmnkit/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 116 out-of-the-box Camunda connector templates as data, 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`.
+
+---
+Source: https://bpmnkit.com/docs/packages/connectors

package/.llms/chunks/packages.connectors.stability.md

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

package/.llms/chunks/packages.connectors.validating-a-template.md

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

package/.llms/chunks/packages.connectors.workspace-templates.md

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