@bpmnkit/docspack 0.0.3 → 0.0.4

package/.llms/chunks/cli.diff.flags.md

@@ -0,0 +1,46 @@
+# casen diff — Flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--format` | `text` | `text` or `json` |
+| `--exit-code` | off | Exit non-zero when the two diagrams differ |
+| `--ascii` | off | Also render both diagrams as ASCII art |
+
+### As a pipeline gate
+
+```sh
+casen diff bpmn main/order.bpmn branch/order.bpmn --exit-code
+```
+
+Exits non-zero when anything differs, so a job can fail — or a review can be requested —
+whenever a pull request touches the shape of a process rather than only its formatting.
+
+### Machine-readable
+
+```sh
+casen diff bpmn old.bpmn new.bpmn --format json
+```
+
+```json
+{
+  "added": ["Activity_1x8fj2"],
+  "removed": [],
+  "changed": ["Activity_0p2ktn"],
+  "moved": ["Gateway_09sd1a"],
+  "total": 3,
+  "planes": [{ "id": "order-process", "total": 3, "added": 1, "removed": 0, "changed": 1, "moved": 1 }]
+}
+```
+
+### Alongside the picture
+
+```sh
+casen diff bpmn old.bpmn new.bpmn --ascii
+```
+
+Prints both diagrams as ASCII art above the summary — the same rendering
+[`casen view`](/docs/cli/view) produces, and the same one the VS Code extension copies into a
+pull request.
+
+---
+Source: https://bpmnkit.com/docs/cli/diff

package/.llms/chunks/cli.diff.md

@@ -0,0 +1,43 @@
+# casen diff
+
+`casen diff bpmn` answers the question a text diff cannot: *what changed about the process?*
+Two files go in, and what comes out is the list of elements a reviewer would see differ —
+named, not just identified.
+
+```sh
+casen diff bpmn old.bpmn new.bpmn
+```
+
+```
+  + Notify Customer (Activity_1x8fj2)
+  ~ Validate Order (Activity_0p2ktn)
+  ⇄ Approved? (Gateway_09sd1a)
+
+3 differences: 1 added, 1 changed, 1 moved
+```
+
+
+## Why the categories matter
+
+| Marker | Category | Means |
+| --- | --- | --- |
+| `+` | added | Exists only in the later file |
+| `−` | removed | Exists only in the earlier file |
+| `~` | changed | Same element, different semantics — a task type, a condition, an extension |
+| `⇄` | moved | Same semantics, different place on the canvas |
+
+`moved` is the category that earns the command. The semantic hash behind
+[`diffSemantics()`](/docs/packages/core#diffsemanticsbefore-after) deliberately drops all
+diagram interchange — that is what makes it stable across a re-layout — so a task somebody
+dragged reads there as no change at all. `casen diff` computes the layout half separately
+from DI (bounds, waypoints, label placement, flags such as collapsed/expanded) and reports it
+as its own category. An element that changed *and* moved is reported as changed, because a
+semantic change is what a reviewer needs first.
+
+Only elements a canvas could actually draw are counted, so a changed `targetNamespace` cannot
+inflate the count against nothing on screen. When a diagram has more than one plane, the
+per-plane totals are printed too — a change inside a collapsed sub-process is invisible in a
+viewer until the reader drills into it.
+
+---
+Source: https://bpmnkit.com/docs/cli/diff

package/.llms/chunks/cli.diff.the-same-diff-elsewhere.md

@@ -0,0 +1,14 @@
+# casen diff — The same diff elsewhere
+
+The comparison itself is
+[`diffDiagram()`](/docs/packages/core#diffdiagrambefore-after) in `@bpmnkit/core`, so every
+surface shows the same answer:
+
+- **Visually, in VS Code** — *Compare Diagram with HEAD*, or two selected files. See the
+  [VS Code guide](/docs/guides/vscode).
+- **On a share link** — `/drop/<before>/diff/<after>`. See the [Drop guide](/docs/guides/drop).
+- **In your own canvas** — `createBpmnDiff()` from `@bpmnkit/plugins` returns a pair of
+  plugins, one per canvas, with synchronised pan and zoom.
+
+---
+Source: https://bpmnkit.com/docs/cli/diff

package/.llms/chunks/guides.building-processes.multi-instance.md

@@ -16,5 +16,71 @@ Run a task or sub-process once per item in a collection:
 })
 ```
 
+
+## Generated IDs
+
+You name every flow node. The builder names everything else, and it derives those names from
+the model so that rebuilding an unchanged process produces unchanged BPMN — a diff that shows
+only what you actually changed.
+
+A sequence flow is named after the two elements it connects:
+
+```typescript
+Bpmn.createProcess("orders")
+  .startEvent("start")
+  .serviceTask("validate", { taskType: "validate" })
+  .endEvent("done")
+  .build()
+// Flow_start_validate, Flow_validate_done
+```
+
+When several flows connect the same pair — the branches of a gateway converging on one join —
+each gets a discriminator taken from the branch name, or from its condition when the branch is
+unnamed:
+
+```typescript
+.exclusiveGateway("gw")
+.branch("approved", (b) => b.connectTo("done"))
+.branch("rejected", (b) => b.connectTo("done"))
+// Flow_gw_gw_join_approved, Flow_gw_gw_join_rejected
+```
+
+Because the id comes from the connection rather than from a counter, adding or reordering an
+unrelated element leaves the other flows' ids alone. The same is true of root definitions
+created from event options — `Message_Order_Received` for `messageName: "Order Received"`, and
+likewise `Error_`, `Signal_` and `Escalation_` from the code or name they carry.
+
+Two consequences worth knowing:
+
+- **Ids are only as stable as the elements they name.** Omitting an element id (`.startEvent()`
+  with no argument) gets you a generated one that changes on every build, and the flow ids
+  around it inherit that. Name the nodes you care about.
+- **`defaultFlow` becomes predictable.** Setting a gateway's default by id no longer requires
+  knowing a random value: `{ defaultFlow: "Flow_gw_gw_join_rejected" }`. `.branch().defaultFlow()`
+  is still the shorter way to say it.
+
+`continueProcess()` never renumbers what the document arrived with: flows the builder did not
+create keep their ids, and new ones avoid them.
+
+### Naming a root definition yourself
+
+When the id of a message, error, signal or escalation matters — because a message flow in another
+pool, a worker, or a deployed process already refers to it — declare it before the events that
+use it:
+
+```typescript
+Bpmn.createProcess("orders")
+  .message("Msg_OrderReceived", { name: "Order Received" })
+  .error("Err_OutOfStock", { code: "OUT_OF_STOCK", name: "Out of stock" })
+  .signal("Sig_Cancelled", { name: "Order Cancelled" })
+  .escalation("Esc_Review", { code: "NEEDS_REVIEW" })
+  .startEvent("start", { messageName: "Order Received" })   // messageRef: Msg_OrderReceived
+```
+
+Events still name these by name or code, exactly as before — the declaration only decides the id
+they resolve to. Order matters: an event built first declares the definition itself, and
+declaring it afterwards under a different id throws rather than leaving two definitions of one
+message behind.
+
 ---
 Source: https://bpmnkit.com/docs/guides/building-processes

package/.llms/chunks/guides.drop.md

@@ -0,0 +1,12 @@
+# Drop — Share & Co-edit
+
+[BPMN Kit Drop](/drop) is the shortest path between a diagram on your machine and the
+person who needs to look at it. Drag a file onto the page, get a short link back, send it.
+Whoever opens the link sees the diagram rendered in their browser — no account, no modeler
+install, and no Camunda cluster anywhere in the story.
+
+It is also where a review happens. A drop is not frozen: anyone with the link can take the
+edit baton, change the diagram, and everyone else watching sees the change arrive.
+
+---
+Source: https://bpmnkit.com/docs/guides/drop

package/.llms/chunks/guides.drop.reviewing-it-together.md

@@ -0,0 +1,45 @@
+# Drop — Share & Co-edit — Reviewing it together
+
+Everything below happens on the share page itself — there is nothing to install on either
+end.
+
+**Live presence.** The topbar counts the people who have the drop open, and says when one
+of them is editing. A diagram moving under a reader's eyes is only unsettling when nothing
+on the page explains it.
+
+**One writer at a time.** Editing is a baton, not a merge. Press **Edit** to claim it and
+the diagram becomes editable for you and stays live for everyone else; press **Done** to
+hand it back. A second person pressing Edit while you hold it is told who has it. There is
+no conflict resolution because there is never a second writer to conflict with.
+
+**No save button.** Changes persist as you make them, so there is no moment at which a
+reviewer can lose work by closing the tab — and none at which they can be asked whether
+they meant it. That is what makes the version log below load-bearing rather than a nicety.
+
+**Version history.** Every file keeps the original it was uploaded as, pinned and never
+overwritten, plus its ten most recent milestones. Repeated saves inside an hour collapse
+into one milestone, and a new editing session always starts its own, so a stranger editing
+at 10:45 cannot overwrite the previous editor's 10:30 state. Restoring **appends**: the
+state being replaced becomes a milestone first, so restoring can never be the thing that
+loses work. Undoing a restore is another restore.
+
+**Visual diff.** Two drops can be put side by side at `/drop/<before>/diff/<after>`: added,
+removed, changed and *moved* elements marked on synchronised canvases, with pan and zoom
+locked together. The same diff is available offline as
+[`casen diff bpmn`](/docs/cli/diff) and as a plugin in `@bpmnkit/plugins`.
+
+Editing is limited to BPMN files with a single process — the editor handles one process at
+a time — and the built-in demo drop is read-only, though **Edit a copy** will upload it as a
+drop of your own.
+
+### Rate limiting the edit baton
+
+Because a drop is editable by anyone holding the link, claiming the baton can be put behind
+a [Turnstile](https://developers.cloudflare.com/turnstile/) challenge — one challenge per
+editing session, not per keystroke. It is invisible to somebody who takes the baton once and
+edits for half an hour, and a real cost to a script that wants to rewrite every drop it can
+find. On a self-hosted deployment it is configuration (`TURNSTILE_SITE_KEY` and
+`TURNSTILE_SECRET`); with neither set, claims are not challenged.
+
+---
+Source: https://bpmnkit.com/docs/guides/drop

package/.llms/chunks/guides.drop.running-your-own.md

@@ -0,0 +1,21 @@
+# Drop — Share & Co-edit — Running your own
+
+Drop is a single Cloudflare Worker in the monorepo (`apps/drop`), MIT-licensed like
+everything else. Files live in D1 as the typed `@bpmnkit/core` model alongside the
+byte-faithful original; presence and live editing are a Durable Object per share.
+
+```sh
+pnpm --filter @bpmnkit/drop build
+wrangler d1 migrations apply bpmnkit-drop --local
+wrangler dev --local --port 8787 \
+  --var DROP_ADMIN_TOKEN:devtoken --var REPORT_IP_SALT:devsalt
+```
+
+That runs the Worker, D1 and the Durable Object in a local simulator, so the whole app works
+offline with no Cloudflare account. For a real deployment,
+`pnpm --filter @bpmnkit/drop provision` is an idempotent script that creates the database,
+applies the migrations, builds the client bundles and deploys the Worker; re-running it
+skips whatever is already in place. See `apps/drop/DEPLOY.md` for the full runbook.
+
+---
+Source: https://bpmnkit.com/docs/guides/drop

package/.llms/chunks/guides.drop.sharing-a-file.md

@@ -0,0 +1,42 @@
+# Drop — Share & Co-edit — Sharing a file
+
+Open <https://bpmnkit.com/drop> and drop a file onto the page — the whole page is the
+target — or paste one from the clipboard. `.bpmn`, `.dmn` and `.form` are all rendered;
+`.xml` and `.json` are accepted and sniffed for the kinds above.
+
+| Limit | Value |
+| --- | --- |
+| Files per drop | 20 |
+| Size of a single file | 900 KB |
+| Total per drop | 5 MB |
+| Retention | 90 days after the last view or edit |
+
+The share id is 11 base58 characters — about 64 bits, so a drop is unguessable and
+unlistable, but it is **not** access-controlled: anyone holding the link can view the
+diagram and take a turn editing it. Treat a drop the way you would treat an unlisted link,
+not the way you would treat a private repository.
+
+You can also start a drop from a diagram you just drew rather than a file you already had:
+the [browser editor](/editor) has **Share as a drop** in its main menu, which uploads the
+open diagram through the same endpoint and the same checks.
+
+### From the command line
+
+A drop is a plain HTTP upload, so `curl` works:
+
+```sh
+curl -s -X POST https://bpmnkit.com/drop/api/drops \
+  -F files=@order-process.bpmn
+# → { "shareId": "7Fq2mKd9xTs", "url": "https://bpmnkit.com/drop/7Fq2mKd9xTs", "files": [...] }
+```
+
+And the stored file comes back either as uploaded or as the parsed model:
+
+```sh
+curl -s https://bpmnkit.com/drop/<shareId>/manifest.json
+curl -s "https://bpmnkit.com/drop/<shareId>/f/order-process.bpmn"                # original bytes
+curl -s "https://bpmnkit.com/drop/<shareId>/f/order-process.bpmn?format=json"    # @bpmnkit/core model
+```
+
+---
+Source: https://bpmnkit.com/docs/guides/drop

package/.llms/chunks/guides.drop.what-drop-is-not.md

@@ -0,0 +1,12 @@
+# Drop — Share & Co-edit — What Drop is not
+
+- **Not a permission system.** Link-holders are editors. If a diagram should not be
+  editable by whoever it reaches, do not put it in a drop.
+- **Not storage.** A drop expires 90 days after it was last touched, and the version log
+  holds eleven states, not every state.
+- **Not a modeler.** It renders and edits one process at a time. For authoring, use the
+  [browser editor](/editor), the [VS Code extension](/docs/guides/vscode) or the
+  [builder API](/docs/packages/core).
+
+---
+Source: https://bpmnkit.com/docs/guides/drop

package/.llms/chunks/guides.vscode.commands.md

@@ -0,0 +1,14 @@
+# VS Code Extension — Commands
+
+| Command | Where |
+| --- | --- |
+| **BPMN Kit: Open Diagram to the Side** | Editor title bar, command palette |
+| **BPMN Kit: Compare Diagram with HEAD** | Source Control context menu, editor title bar |
+| **BPMN Kit: Compare Diagrams Visually** | Explorer, with exactly two `.bpmn` files selected |
+| **BPMN Kit: Open FEEL Playground** | Command palette — pre-filled from the selection |
+| **BPMN Kit: Copy Diagram as ASCII** | Editor title bar, Explorer, command palette |
+| **BPMN Kit: Deploy to Camunda 8** | Command palette |
+| **BPMN Kit: Deploy and Start Instance** | Explorer, command palette |
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.installing.md

@@ -0,0 +1,22 @@
+# VS Code Extension — Installing
+
+The extension is **pre-1.0 and not on the Marketplace yet** — it is built from the monorepo
+and ships when the packages it is built from do:
+
+```sh
+git clone https://github.com/bpmnkit/monorepo
+cd monorepo && pnpm install
+pnpm --filter bpmnkit build
+pnpm --filter bpmnkit package     # → apps/vscode/bpmnkit.vsix
+```
+
+Then install the `.vsix`: **Extensions → … → Install from VSIX…**, or
+
+```sh
+code --install-extension apps/vscode/bpmnkit.vsix
+```
+
+It activates on a workspace containing a `.bpmn` file, and requires VS Code 1.90 or newer.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.md

@@ -0,0 +1,13 @@
+# VS Code Extension
+
+**BPMN Kit for VS Code** puts the toolkit where the code already is. It renders `.bpmn`,
+`.dmn` and `.form` files, reports the same findings `casen lint` reports, compares a diagram
+against `HEAD`, runs the process without a cluster, and edits the file without reformatting
+it.
+
+The renderer is [`@bpmnkit/canvas`](/docs/packages/canvas), the same from-scratch BPMN 2.0
+implementation the website and the browser editor use. There is no bpmn.io anywhere in the
+extension, which is the point: the files it shows you are the files git has, byte for byte.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.settings.md

@@ -0,0 +1,19 @@
+# VS Code Extension — Settings
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `bpmnkit.lint.enabled` | `true` | Report findings in the Problems panel |
+| `bpmnkit.lint.run` | `onType` | `onType` or `onSave` |
+| `bpmnkit.lint.forceEngineRules` | `false` | Apply Camunda 8 rules to an engine-neutral diagram |
+| `bpmnkit.viewer.grid` | `true` | Dot grid behind the diagram |
+| `bpmnkit.viewer.minimap` | `true` | Minimap in the BPMN viewer |
+| `bpmnkit.simulation.enabled` | `true` | Offer step-through simulation in the preview |
+| `bpmnkit.editing.enabled` | `true` | Let the diagram editor change the file |
+
+Findings are reported for `.bpmn` files that are open; a file the editor has not loaded is
+not analysed, same as every other linter in VS Code. Set `bpmnkit.editing.enabled` to `false`
+for the same editors with editing switched off, when a diagram should be openable with no
+chance of changing it.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.support.md

@@ -0,0 +1,11 @@
+# VS Code Extension — Support
+
+The extension is pre-1.0 and community-supported, developed in the open in the
+[monorepo](https://github.com/bpmnkit/monorepo) alongside the packages it is built from.
+Minor versions may change behaviour before 1.0: the features above will not disappear, but
+setting names and command titles may still move. Bugs and requests go to
+[GitHub issues](https://github.com/bpmnkit/monorepo/issues). MIT-licensed, like everything
+else in the repository.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-a-feel-playground-on-your-selection.md

@@ -0,0 +1,8 @@
+# VS Code Extension — What it does — A FEEL playground on your selection
+
+Select an expression anywhere in the XML and open the playground: it comes up pre-filled,
+with a context you can edit and the result evaluated as you type. Unary tests too, for
+decision-table input entries.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-a-visual-diff-in-source-control.md

@@ -0,0 +1,11 @@
+# VS Code Extension — What it does — A visual diff in Source Control
+
+Right-click a `.bpmn` file in Source Control to see it against `HEAD`, or select exactly two
+in the Explorer to compare them with each other. Added, removed, changed and moved elements
+are marked on synchronised canvases — a moved element reads as *moved*, not as two unrelated
+pictures. The text diff stays where it was; this is a second view of the same change, not a
+replacement for the first. The same comparison is available as
+[`casen diff bpmn`](/docs/cli/diff) and on a [drop](/docs/guides/drop).
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-copy-the-diagram-as-text.md

@@ -0,0 +1,8 @@
+# VS Code Extension — What it does — Copy the diagram as text
+
+For a code review, where a picture cannot go. **BPMN Kit: Copy Diagram as ASCII** renders the
+layout into a fenced block that pastes into a pull request, an issue or a commit message,
+dedented so the diagram is not mostly margin.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-deploy-against-your-own-clusters.md

@@ -0,0 +1,21 @@
+# VS Code Extension — What it does — Deploy against your own clusters
+
+Deployment targets come from `casen`'s profile store — the same file
+[`casen profile create`](/docs/cli/casen#connection-profiles) writes — so there is no second
+place to configure a cluster and no credentials in your workspace settings:
+
+```sh
+casen profile create staging --base-url https://<cluster>.camunda.io/<id> \
+  --auth-type oauth --client-id … --client-secret …
+```
+
+Every `c8` profile then appears in the extension. Deploy the open file, or deploy and start
+an instance with variables; the instance key comes back in a notification. Deploy-and-start
+also offers the payloads it finds in `.camunda/payloads/*.json`, walking up from the diagram,
+so the inputs a process is always tried with are a pick rather than a paste.
+
+Credentials are read only to sign the request — nothing in the extension stores, displays or
+logs them.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-editing-that-leaves-a-readable-diff.md

@@ -0,0 +1,22 @@
+# VS Code Extension — What it does — Editing that leaves a readable diff
+
+The diagram editor is a **text** custom editor: it edits the same `TextDocument` a text
+editor would open. The file is dirty when the document is, <kbd>Ctrl</kbd>+<kbd>S</kbd>
+saves it, hot exit restores it, undo is the editor's own undo, and a text editor open on the
+same file is a second view of one document rather than a competing copy. Type in the XML and
+the diagram follows; move a box and the XML follows.
+
+Saving writes a diff a reviewer can read. A visual editor normally serialises the whole
+model, which reformats the file on the first change and buries one edit in a rewrite of
+everything. This one writes the file that was already there: renaming a task changes the
+line with the task on it, moving a box changes two numbers, and your indentation, attribute
+order and comments come back untouched. Opening a diagram and saving it without editing
+anything leaves the file byte for byte. Form files get the same treatment — indentation, key
+order and trailing newline all survive.
+
+That behaviour is not extension-specific; it is
+[`exportPreserving()`](/docs/packages/core#exportpreservingoriginal-definitions) from
+`@bpmnkit/core`, available to anything that writes a model back over a file it parsed.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-findings-in-the-problems-panel.md

@@ -0,0 +1,13 @@
+# VS Code Extension — What it does — Findings in the Problems panel
+
+The same static analysis `casen lint` runs — flow reachability, naming, FEEL syntax, data
+flow, Camunda 8 deployability — reported against the element that caused it, so clicking a
+problem takes you to the tag rather than to line 1.
+
+The analysis matches the file. A diagram that declares no `modeler:executionPlatform` is not
+judged against Camunda 8 deployability, because "this service task has no
+`zeebe:taskDefinition`" is not a defect in a diagram that was never going to be deployed to
+Zeebe. Turn on `bpmnkit.lint.forceEngineRules` to apply those rules anyway.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-preview-beside-the-source.md

@@ -0,0 +1,12 @@
+# VS Code Extension — What it does — Preview beside the source
+
+`.bpmn`, `.dmn` and `.form` all render, with a minimap and zoom for BPMN. The preview
+follows the buffer as you type rather than on save, and when the XML is momentarily
+unparseable it keeps the last drawing that worked rather than blanking.
+
+The text editor stays the default for all three file types. Open the diagram with
+**BPMN Kit: Open Diagram to the Side**, with *Reopen Editor With…*, or make it your default
+through `workbench.editorAssociations`.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/guides.vscode.what-it-does-run-the-diagram-in-the-editor.md

@@ -0,0 +1,9 @@
+# VS Code Extension — What it does — Run the diagram in the editor
+
+[`@bpmnkit/engine`](/docs/packages/engine) is a BPMN engine written in TypeScript, so the
+preview does not need a cluster to execute what is on screen. Press **Run** and watch tokens
+move; press **One Step** to advance the instance one element at a time, reading the variables
+as they change. Nothing is deployed and nothing leaves your machine.
+
+---
+Source: https://bpmnkit.com/docs/guides/vscode

package/.llms/chunks/packages.core.installation-ad-hoc-sub-processes-children-are-a-set-not-a-chain.md

@@ -0,0 +1,42 @@
+# @bpmnkit/core — Installation — Ad-hoc sub-processes: children are a set, not a chain
+
+Sequential calls in a builder chain auto-connect with sequence flows. Inside
+`.adHocSubProcess()` they do not: BPMN defines an ad-hoc sub-process's children as an unordered
+set of independently-invocable activities, and Camunda 8's agentic AI runtime reads that
+structurally — a child *without* an incoming flow is an LLM-invocable tool, a child *with* one
+is part of an internal sub-flow and not a tool at all.
+
+```typescript
+.adHocSubProcess("agent", (s) => {
+  s.serviceTask("listUsers",  { taskType: "io.camunda:http-json:1" });
+  s.serviceTask("loadUser",   { taskType: "io.camunda:http-json:1" });
+  s.serviceTask("createUser", { taskType: "io.camunda:http-json:1" });
+}, { name: "Handle request" })
+// → three tools, no sequence flows, no <bpmndi:BPMNEdge> between them
+```
+
+Auto-chaining them produced a file that lints clean and deploys, while the agent saw one tool
+and a two-step sub-flow — so the default is off rather than opt-out.
+
+An internal sub-flow inside the container stays expressible: say so with `.connectTo()`, which
+still creates a flow from the cursor.
+
+```typescript
+.adHocSubProcess("agent", (s) => {
+  s.serviceTask("listUsers", { taskType: "io.camunda:http-json:1" });   // a tool
+  s.serviceTask("step1", { taskType: "work" }).connectTo("step2");      // an internal sub-flow
+  s.serviceTask("step2", { taskType: "work" });
+})
+```
+
+Each child's LLM-facing description is its `documentation`, which every builder method accepts:
+
+```typescript
+s.serviceTask("listUsers", {
+  taskType: "io.camunda:http-json:1",
+  documentation: "Call this to retrieve all users. Returns id, name, email.",
+});
+```
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.installation-compactify-definitions.md

@@ -1,10 +1,15 @@
 # @bpmnkit/core — Installation — `compactify(definitions)`
 
 Projects a `BpmnDefinitions` object onto a `CompactDiagram` — a small JSON object suitable
-for LLM prompts. **Lossy:** it keeps topology, names and the common Zeebe bindings, and drops
-collaborations, participants, message flows, lanes, data stores, artifacts, root-level
-messages and errors, multi-instance loop characteristics, full `zeebe:ioMapping` entries and
-diagram interchange.
+for LLM prompts. **Lossy:** it keeps topology, names, `<bpmn:documentation>` and the common
+Zeebe bindings, and drops collaborations, participants, message flows, lanes, data stores,
+artifacts, root-level messages and errors, multi-instance loop characteristics, full
+`zeebe:ioMapping` entries and diagram interchange.
+
+`documentation` is carried on every element and on the process itself, because in Camunda 8 it
+is not decoration: on an ad-hoc sub-process child it is the tool description handed to the LLM,
+and on a start event it is where the process input contract is written. It had been dropped, so
+a single `rename` operation cost a file the documentation of every element in it.
 
 ```typescript
 import { compactify } from "@bpmnkit/core";

package/.llms/chunks/packages.core.installation-createflowelement-id-type-options.md

@@ -0,0 +1,7 @@
+# @bpmnkit/core — Installation — `createFlowElement(id, type, options?)`
+
+Builds an empty flow element of any `BpmnElementType`, with the right shape for that type.
+This is the single place that mapping lives; the fluent builder uses it too.
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.installation-diffdiagram-before-after.md

@@ -0,0 +1,33 @@
+# @bpmnkit/core — Installation — `diffDiagram(before, after)`
+
+What a *reviewer* would see change — `diffSemantics()` plus the layout half it deliberately
+ignores, restricted to elements a canvas can actually draw.
+
+```typescript
+import { diffDiagram } from "@bpmnkit/core";
+
+const result = diffDiagram(before, after);
+result.added;    // ids only in `after`
+result.removed;  // ids only in `before`
+result.changed;  // same element, different semantics
+result.moved;    // same semantics, different place on the canvas
+result.total;
+result.planes;   // per-plane breakdown — a change inside a collapsed sub-process
+                 // is invisible in a viewer until the reader drills into it
+```
+
+`moved` is why this exists. The semantic hash drops all diagram interchange — that is what
+makes it stable across a re-layout — so a task somebody dragged reads as no change at all in
+`diffSemantics()`. Here the geometry is compared separately from DI (bounds, waypoints, label
+placement, and flags such as collapsed/expanded). An element that changed *and* moved is
+reported as changed, since a semantic change is what a reviewer needs first.
+
+An element with nothing to draw on either side is left out, so a changed `targetNamespace`
+cannot inflate a count against nothing on screen.
+
+The same comparison is [`casen diff bpmn`](/docs/cli/diff) on the command line,
+`createBpmnDiff()` in `@bpmnkit/plugins` on a pair of canvases, and *Compare Diagram with
+HEAD* in the [VS Code extension](/docs/guides/vscode).
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.installation-element-catalog.md

@@ -0,0 +1,10 @@
+# @bpmnkit/core — Installation — Element catalog
+
+`ELEMENT_TYPE_GROUPS` maps every `BpmnElementType` to one of `event`, `task`, `gateway`,
+`container` or `data`, with `allElementTypes()` and `elementTypesInGroup(group)` over it. Tool
+schemas and prompts render their type lists from this rather than hard-coding one — a
+hand-written list is how the MCP schema came to advertise 18 types while the compact path
+accepted 23.
+
+---
+Source: https://bpmnkit.com/docs/packages/core