@bpmnkit/docspack 0.0.5 → 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.minimal-empty-diagram.md

@@ -24,6 +24,7 @@ Rules:
 - Use camelCase IDs
 - Every service task needs a taskType 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
 ```

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/guides.using-bpmnkit-with-ai.asking.md

@@ -0,0 +1,47 @@
+# Using BPMN Kit with AI — 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
+```
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.from-the-library-instead-of-the-cli-the-other-route-docspack-index.md

@@ -0,0 +1,56 @@
+# Using BPMN Kit with AI — From the library instead of the CLI — 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.
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.from-the-library-instead-of-the-cli.md

@@ -0,0 +1,86 @@
+# Using BPMN Kit with AI — 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
+
+  ```
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.md

@@ -0,0 +1,17 @@
+# Using BPMN Kit 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.
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.runnable-examples.md

@@ -0,0 +1,31 @@
+# Using BPMN Kit with AI — Runnable examples
+
+Three scripts in [`apps/examples/src/ai`](https://github.com/bpmnkit/monorepo/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.
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.telling-an-agent-they-exist.md

@@ -0,0 +1,23 @@
+# Using BPMN Kit with AI — 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.
+```
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.the-two-packs-bpmn-kit-ships.md

@@ -0,0 +1,20 @@
+# Using BPMN Kit with AI — 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.
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai

package/.llms/chunks/guides.using-bpmnkit-with-ai.the-whole-loop-five-markdown-files-to-a-bpmn-diagram.md

@@ -0,0 +1,64 @@
+# Using BPMN Kit with AI — 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.
+
+---
+Source: https://bpmnkit.com/docs/guides/using-bpmnkit-with-ai