@bpmnkit/docspack 0.0.2 → 0.0.4

package/.llms/chunks/cli.casen.aikit-skills.md

@@ -13,7 +13,7 @@ casen skills install
 | `/test <path>` | Run scenario tests and report path/branch coverage |
 | `/deploy <path>` | Deploy-readiness gate, then deploy to local Reebe or Camunda 8 |
 
-For the richer skill set (`/bpmnkit:implement`, `:extend`, `:agent`, `:connect`, plus generated reference docs), install the Claude Code plugin instead: `/plugin marketplace add github:bpmnkit/monorepo` then `/plugin install bpmnkit`. See [AIKit Skills](/cli/skills/) for full documentation.
+For the richer skill set (`/bpmnkit:implement`, `:extend`, `:agent`, `:connect`, plus generated reference docs), install the Claude Code plugin instead: `/plugin marketplace add github:bpmnkit/monorepo` then `/plugin install bpmnkit`. See [AIKit Skills](/docs/cli/skills) for full documentation.
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.bpmn-generation-pipeline.md

@@ -26,7 +26,7 @@ casen deploy deploy order-process.bpmn --target camunda8 # active Camunda 8 prof
 
 `casen synth` reports any problems keyed by JSON path in the plan (e.g. `steps[2].connector.values.token`) — fix the plan, never the XML, and re-run. If the plan has a `tests` array, `casen synth` also writes a `<file>.bpmn.tests.json` sidecar, runnable with `casen test <file>.bpmn`.
 
-See [Building Processes with AI](/guides/ai-implement/) and [AI Agents](/guides/ai-agents/) for full walkthroughs.
+See [Building Processes with AI](/docs/guides/ai-implement) and [AI Agents](/docs/guides/ai-agents) for full walkthroughs.
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.connection-profiles.md

@@ -59,4 +59,4 @@ Variables (JSON): {"method": "card"}
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.generate-bpmn-files.md

@@ -9,7 +9,7 @@ casen generate bpmn --input order.bpmn --dump-compact   # inspect as JSON for AI
 casen generate bpmn --input order.bpmn --patch '{"elements":[...],"flows":[...]}'
 ```
 
-See [casen generate](/cli/generate/) for full documentation.
+See [casen generate](/docs/cli/generate) for full documentation.
 
 
 ## View BPMN, DMN, and Form files
@@ -22,7 +22,7 @@ casen view dmn routing.dmn       # DMN decision table
 casen view open ./project/       # any mix of .bpmn/.dmn/.form
 ```
 
-See [casen view](/cli/view/) for full documentation.
+See [casen view](/docs/cli/view) for full documentation.
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.mcp-server-mode.md

@@ -0,0 +1,31 @@
+# casen CLI — MCP Server Mode
+
+`casen` can act as an MCP (Model Context Protocol) server, exposing all cluster operations
+as tools to Claude Desktop, Cursor, or any MCP client:
+
+```sh
+casen mcp
+```
+
+Configure in Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "camunda": {
+      "command": "casen",
+      "args": ["mcp"],
+      "env": {
+        "CAMUNDA_CLIENT_ID": "...",
+        "CAMUNDA_CLIENT_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+Now you can ask Claude: _"Show me the open incidents on the invoice-approval process"_ or
+_"Resolve all incidents on process instance 2251799813685249"_.
+
+---
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.md

@@ -77,4 +77,4 @@ casen
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.plugins.md

@@ -50,7 +50,7 @@ casen plugin remove casen-deploy
 
 Once installed, plugin commands appear in the main TUI and in tab-completion alongside built-in commands.
 
-To build your own plugin, see [Plugin Authoring](/cli/plugin-authoring/).
+To build your own plugin, see [Plugin Authoring](/docs/cli/plugin-authoring).
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.casen.worker-commands.md

@@ -12,34 +12,31 @@ casen worker start send-invoice
 ```
 
 
-## MCP Server Mode
+## Local engine (Reebe)
 
-`casen` can act as an MCP (Model Context Protocol) server, exposing all cluster operations
-as tools to Claude Desktop, Cursor, or any MCP client:
+Reebe is a Zeebe-compatible workflow engine (~50 MB) that runs locally, so you can deploy
+and run processes without a Camunda 8 cluster.
 
 ```sh
-casen mcp
-```
+# Embedded SQLite, no external database
+casen reebe start
+
+# Custom port — match ZEEBE_ADDRESS, which defaults to http://localhost:26500
+casen reebe start --port 26500
 
-Configure in Claude Desktop (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "camunda": {
-      "command": "casen",
-      "args": ["mcp"],
-      "env": {
-        "CAMUNDA_CLIENT_ID": "...",
-        "CAMUNDA_CLIENT_SECRET": "..."
-      }
-    }
-  }
-}
+# PostgreSQL instead of the embedded database
+casen reebe start --database-url postgres://user:pass@localhost/reebe
 ```
 
-Now you can ask Claude: _"Show me the open incidents on the invoice-approval process"_ or
-_"Resolve all incidents on process instance 2251799813685249"_.
+| Flag | Default | Description |
+|---|---|---|
+| `--port` | `8080` | HTTP port to listen on |
+| `--database-url` | embedded SQLite | PostgreSQL connection URL |
+| `--config` | `config.toml` | Path to the engine config file |
+
+`casen reebe` on its own is shorthand for `casen reebe start`. The command runs the
+`reebe-server` binary; build it with
+`cargo install --path apps/reebe/crates/reebe-server` if it is not on your `PATH`.
 
 ---
-Source: https://docs.bpmnkit.com/cli/casen/
+Source: https://bpmnkit.com/docs/cli/casen

package/.llms/chunks/cli.connector.all-flags.md

@@ -26,4 +26,4 @@
 Auth is auto-detected from `components.securitySchemes` in the spec. Use `--auth` to override.
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.browse-the-bundled-ootb-catalog.md

@@ -8,7 +8,7 @@ casen connector show io.camunda.connectors.Slack.v1
 `search` scores the 116 bundled templates by keyword match and prints a table (template id,
 direction, task type, description). `show` prints a template's task type, direction, and its
 required/optional input keys — these are the keys a `ProcessPlan` `connector` step's `values`
-object uses (see [Building Processes with AI](/guides/ai-implement/)):
+object uses (see [Building Processes with AI](/docs/guides/ai-implement)):
 
 ```
 $ casen connector show io.camunda.connectors.Slack.v1
@@ -29,4 +29,4 @@ credential. This is the same catalog `@bpmnkit/connectors`' `listConnectors()`/`
 expose programmatically.
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.built-in-catalog.md

@@ -38,4 +38,4 @@ casen connector catalog
 | `brex` | Brex API | oauth-client-credentials-flow |
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.common-workflows.md

@@ -47,4 +47,4 @@ casen connector generate --swagger ./openapi.yaml \
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.generate-from-the-openapi-catalog.md

@@ -27,4 +27,4 @@ casen connector generate --swagger ./api-spec.json --output ./templates/
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.md

@@ -17,4 +17,4 @@ casen connector
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.programmatic-usage.md

@@ -1,7 +1,7 @@
 # casen connector — Programmatic usage
 
 The underlying generator is available as a standalone package for use in Node.js scripts and build
-pipelines. See [`@bpmnkit/connector-gen`](/packages/connector-gen/).
+pipelines. See [`@bpmnkit/connector-gen`](/docs/packages/connector-gen).
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

package/.llms/chunks/cli.connector.what-gets-generated.md

@@ -17,4 +17,4 @@ Import the generated `.json` files into Camunda Modeler via
 **File → Import Element Templates** or by placing them in your `.camunda/element-templates/` directory.
 
 ---
-Source: https://docs.bpmnkit.com/cli/connector/
+Source: https://bpmnkit.com/docs/cli/connector

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/cli.generate.definition-mode-ai-scripting-path.md

@@ -86,4 +86,4 @@ casen generate bpmn --help-schema
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/generate/
+Source: https://bpmnkit.com/docs/cli/generate

package/.llms/chunks/cli.generate.md

@@ -49,4 +49,4 @@ casen generate bpmn --template timer-start --process-id nightly-sync
 | `--output` | `-o` | Output file path (`-` for stdout) | `<process-id>.bpmn` |
 
 ---
-Source: https://docs.bpmnkit.com/cli/generate/
+Source: https://bpmnkit.com/docs/cli/generate

package/.llms/chunks/cli.generate.modify-existing-mode-input.md

@@ -56,4 +56,4 @@ casen generate bpmn --input messy.bpmn --output clean.bpmn
 | `--output` / `-o` | Output path (`-` for stdout) | Overwrites `--input` file |
 
 ---
-Source: https://docs.bpmnkit.com/cli/generate/
+Source: https://bpmnkit.com/docs/cli/generate

package/.llms/chunks/cli.generate.typical-ai-workflow.md

@@ -15,4 +15,4 @@ casen view bpmn order.bpmn
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/generate/
+Source: https://bpmnkit.com/docs/cli/generate

package/.llms/chunks/cli.plugin-authoring.md

@@ -56,4 +56,4 @@ pnpm create @bpmnkit/casen-plugin \
 | `--no-git` | Skip `git init` |
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugin-authoring.plugin-naming-conventions.md

@@ -8,4 +8,4 @@
 | Prefix group name with your org for internal plugins | e.g. `acme-deploy` avoids clashing with a published `casen-deploy` |
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugin-authoring.test-locally.md

@@ -38,4 +38,4 @@ casen plugin search deploy
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugin-authoring.the-bpmnkit-cli-sdk-sdk.md

@@ -79,4 +79,4 @@ ctx.output.print(anything)                      // raw, format-aware
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugin-authoring.what-gets-generated.md

@@ -66,4 +66,4 @@ export default plugin
 Replace the example command with your own logic. Add as many command groups and commands as needed.
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugin-authoring.writing-commands.md

@@ -81,4 +81,4 @@ async run(ctx) {
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugin-authoring/
+Source: https://bpmnkit.com/docs/cli/plugin-authoring

package/.llms/chunks/cli.plugins.bpmnkit-casen-report.md

@@ -36,4 +36,4 @@ casen plugin install @bpmnkit/casen-worker-ai
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugins/
+Source: https://bpmnkit.com/docs/cli/plugins

package/.llms/chunks/cli.plugins.bpmnkit-casen-worker-http.md

@@ -17,7 +17,7 @@ casen plugin install @bpmnkit/casen-worker-http
 
 ## Authoring Plugins
 
-See the [Plugin Authoring](/cli/plugin-authoring/) guide to build and publish your own `casen` plugin.
+See the [Plugin Authoring](/docs/cli/plugin-authoring) guide to build and publish your own `casen` plugin.
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugins/
+Source: https://bpmnkit.com/docs/cli/plugins

package/.llms/chunks/cli.plugins.md

@@ -1,8 +1,7 @@
 # casen Plugins
 
-:::note[Auto-generated]
-This page is generated from `plugins-cli/*/package.json` during the docs build. Do not edit manually.
-:::
+> **Auto-generated** — this page is built from `plugins-cli/*/package.json` during the site
+> build. Do not edit it by hand.
 
 Official plugins extend `casen` with domain-specific command groups. Install them with:
 
@@ -22,4 +21,4 @@ casen plugin install <name>
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/plugins/
+Source: https://bpmnkit.com/docs/cli/plugins

package/.llms/chunks/cli.skills.deploy.md

@@ -21,4 +21,4 @@ Gate a BPMN process on deploy-readiness, then deploy it to local Reebe or Camund
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.skills.implement.md

@@ -28,9 +28,9 @@ Tests: 3/3 passed
 Deploy to local Reebe, deploy to Camunda 8, or skip?
 ```
 
-See [Building Processes with AI](/guides/ai-implement/) for a full walkthrough.
+See [Building Processes with AI](/docs/guides/ai-implement) for a full walkthrough.
 
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.skills.md

@@ -6,7 +6,7 @@ They drive `casen` directly (no MCP server, no proxy daemon).
 
 For the full skill set — `/bpmnkit:implement`, `:extend`, `:agent`, `:connect`, plus generated
 reference docs the skills read before authoring a plan — install the
-[Claude Code plugin](/guides/ai-implement/#the-claude-code-plugin) instead.
+[Claude Code plugin](/docs/guides/ai-implement#the-claude-code-plugin) instead.
 
 
 ## Installation
@@ -26,4 +26,4 @@ casen skills install --force
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.skills.no-mcp-server-required.md

@@ -3,4 +3,4 @@
 These skills are plain Bash + Read/Write — they call `casen` directly and never depend on an MCP server or a running proxy. The `@bpmnkit/proxy` MCP server (`bpmn-aikit`) still exists separately, for Claude Desktop/Cursor or other MCP-only hosts — it's unrelated to these slash commands.
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.skills.review.md

@@ -30,4 +30,4 @@ Deploy-ready: no — 1 error
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.skills.test.md

@@ -30,4 +30,4 @@ Uncovered paths:
 ---
 
 ---
-Source: https://docs.bpmnkit.com/cli/skills/
+Source: https://bpmnkit.com/docs/cli/skills

package/.llms/chunks/cli.view.folder-support.md

@@ -28,4 +28,4 @@ casen view bpmn process.bpmn --theme dark --port 8080 --no-open
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/view/
+Source: https://bpmnkit.com/docs/cli/view

package/.llms/chunks/cli.view.md

@@ -67,4 +67,4 @@ casen view form ./forms/
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/view/
+Source: https://bpmnkit.com/docs/cli/view

package/.llms/chunks/cli.view.tabbed-navigation.md

@@ -25,4 +25,4 @@ casen view bpmn order.bpmn --no-open --port 3044
 ```
 
 ---
-Source: https://docs.bpmnkit.com/cli/view/
+Source: https://bpmnkit.com/docs/cli/view

package/.llms/chunks/getting-started.concepts.ai-compact-format.md

@@ -16,8 +16,19 @@ const restored = expand(compact);
 The compact format is designed for AI agents:
 - Every element has an `id` and a human-readable `name`
 - Sequence flows are represented as `{ from, to, condition? }` pairs
-- Zeebe extensions (task type, IO mappings, headers) are inlined
+- Common Zeebe extensions (task type, headers, form and decision bindings) are inlined
 - The full diagram of a typical approval workflow fits in ~500 tokens
 
+> **`compactify()` is a lossy view, not a round trip.** `CompactElement` models about fifteen
+> properties, so `expand(compactify(definitions))` is not `definitions`: collaborations,
+> participants, message flows, lanes, data stores, artifacts, root-level messages and errors,
+> multi-instance loop characteristics, full `zeebe:ioMapping` entries and most diagram
+> interchange do not survive it.
+>
+> Use it to **show** a model to an LLM and to build a **new** model from one. Do not use it as
+> an edit path for a file you need to keep — read the file, apply the change to the
+> `BpmnDefinitions`, and export that. For the same reason `casen generate bpmn --input`
+> refuses to overwrite its input unless you pass `--force`.
+
 ---
-Source: https://docs.bpmnkit.com/getting-started/concepts/
+Source: https://bpmnkit.com/docs/getting-started/concepts

package/.llms/chunks/getting-started.concepts.auto-layout.md

@@ -21,4 +21,4 @@ Under the hood, the layout algorithm:
 You can access element sizes via the `ELEMENT_SIZES` export if you need to build custom layouts.
 
 ---
-Source: https://docs.bpmnkit.com/getting-started/concepts/
+Source: https://bpmnkit.com/docs/getting-started/concepts

package/.llms/chunks/getting-started.concepts.parsing-and-serializing.md

@@ -1,17 +1,16 @@
 # Core Concepts — Parsing and Serializing
 
-The SDK can round-trip any BPMN 2.0 XML — parse it, modify it in TypeScript, and export it back:
+Parse BPMN 2.0 XML into a typed object, modify it in TypeScript, and export it back:
 
 ```typescript
-import { Bpmn } from "@bpmnkit/core";
+import { Bpmn, findProcess } from "@bpmnkit/core";
 
 // Parse XML into a typed object
 const definitions = Bpmn.parse(xmlString);
 
-// Access the first process
-const process = definitions.rootElements.find(
-  (el) => el.$type === "bpmn:Process"
-);
+// Access the first process, or look one up by id
+const process = definitions.processes[0];
+const approval = findProcess(definitions, "approval-flow");
 
 // Export back to XML
 const newXml = Bpmn.export(definitions);
@@ -19,8 +18,49 @@ const newXml = Bpmn.export(definitions);
 
 ### Round-trip fidelity
 
-The parser preserves all attributes, extensions, and vendor-specific elements. Exporting the
-parsed object produces XML that is semantically equivalent to the input.
+`Bpmn.parse()` → `Bpmn.export()` preserves the document. Content the SDK models round-trips
+through its typed fields; content it does not model is kept verbatim and re-emitted:
+
+- **Unmodelled attributes** land in `unknownAttributes` on the element that carried them.
+- **Unmodelled children** of `definitions`, a `process`, a `collaboration`, a flow node, a
+  `multiInstanceLoopCharacteristics` or a data association land in `unknownChildren` — so
+  `bpmn:import`, `bpmn:itemDefinition`, `bpmn:ioSpecification`, `bpmn:correlationKey`,
+  `bpmn:potentialOwner`, `bpmn:complexBehaviorDefinition` and vendor elements outside
+  `extensionElements` all survive, including their nested content.
+- **`extensionElements`** are kept as raw `XmlElement` trees wherever BPMN allows them,
+  including on root-level `message`, `error`, `escalation` and `signal` elements — which is
+  what carries `zeebe:subscription` correlation keys.
+
+`semanticHash(definitions)` gives you this as a check you can run yourself: it hashes the
+model with the diagram excluded, so `semanticHash(applyAutoLayout(defs))` equals
+`semanticHash(defs)`, and any difference means the model changed rather than the layout.
+
+A corpus of BPMN documents is round-tripped on every build and compared structurally —
+element counts, per-element attribute names, parent/child nesting and text content — by a
+scanner written independently of the parser, so a regression fails CI rather than reaching a
+release. See `packages/core/tests/roundtrip-corpus.test.ts`.
+
+A second gate works from the other direction. The corpus can only find losses in documents
+somebody wrote; this one asks the BPMN, DI and Zeebe schema descriptors what exists at all,
+builds a document containing each of the 151 types they define, and requires it to come back
+out — as a typed field or verbatim. A descriptor bump that widens the specification fails the
+build instead of quietly widening the loss. See
+`packages/core/tests/descriptor-coverage.test.ts`, or run
+`pnpm --filter @bpmnkit/core check:descriptors` for the report.
+
+**Deliberate normalisations.** The output is not byte-identical to the input, and two rewrites
+are intentional:
+
+- `isExecutable="false"` and `isSequential="false"` are written only when true. BPMN treats
+  the absent attribute as false, so this is stable and changes nothing.
+- Empty `<extensionElements/>` elements are dropped, and whitespace and attribute order are
+  not preserved.
+
+**Still not preserved.** Unmodelled *children* are captured on the containers listed above
+only. On other elements — lanes, artifacts, root-level messages and errors —
+`documentation` and `extensionElements` round-trip, but any other unrecognised child does
+not. A second `<documentation>` on the same element is also dropped;
+only the first is kept. If you need one of these, open an issue rather than working around it.
 
 ---
-Source: https://docs.bpmnkit.com/getting-started/concepts/
+Source: https://bpmnkit.com/docs/getting-started/concepts