@eventcatalog/core 5.0.0-beta.9 → 5.0.1

package/dist/docs/development/guides/domains/04-add-resources-to-domains/01-add-systems-to-domains.md

@@ -11,7 +11,7 @@ description: Add systems to domains so users can move from a business boundary t
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 A [system](/docs/development/guides/systems/introduction) is a collection of resources that work together to perform a function.
 
@@ -129,6 +129,8 @@ systems:
 
 Use this view when you want readers to understand the systems inside a domain before they drill into lower-level resources.
 
+To see the systems in the visualizer, open **Diagram** in the domain sidebar. Level 1 shows the domain's systems and the other domains they talk to, and level 2 expands each system into its services and data stores. Learn more in [Domain diagram](/docs/development/guides/domains/visualize-domains/domain-diagram).
+
 ## Linking to systems from domain docs
 
 You can link to systems from domain Markdown using resource references.

package/dist/docs/development/guides/domains/04-add-resources-to-domains/02-add-services-to-domains.md

@@ -82,5 +82,9 @@ Although it's recommended to link to a version of a service it is now optional.
 
 When you view your domain in EventCatalog, the services will be visualized for you.
 
-![Example](../../img/domains/visualiser.png)
+Open **Diagram** in the domain sidebar and switch to level 2 (**L2**) to see the domain's services and data stores, grouped by system. Level 3 (**L3**) adds the messages and channels between them.
+
+![Payments domain diagram at level 2, showing services inside their systems](../06-visualize-domains/img/domain-diagram-l2.png)
+
+Learn more in [Domain diagram](/docs/development/guides/domains/visualize-domains/domain-diagram).
 

package/dist/docs/development/guides/domains/04-add-resources-to-domains/03-add-messages-to-domains.md

@@ -96,9 +96,9 @@ Although it's recommended to link to a version of a message it is now optional.
 
 ## Visualizing messages within a domain
 
-Messages are shown in the sidebar of your domain under "Publishes Messages" and "Consumes Messages" sections. There is currently no visualizer support for messages at the domain level.
+Messages are shown in the sidebar of your domain under "Publishes Messages" and "Consumes Messages" sections.
 
-_Coming soon: Visualizer support for messages at the domain level._
+To see messages in the visualizer, open **Diagram** in the domain sidebar and switch to level 3 (**L3**). Level 3 adds the messages and channels that the domain's services send and receive. Learn more in [Domain diagram](/docs/development/guides/domains/visualize-domains/domain-diagram).
 
 ## Making changes and versioning
 

package/dist/docs/development/guides/domains/04-add-resources-to-domains/05-add-entities-to-domains.md

@@ -61,7 +61,7 @@ For services, the route is:
 /visualiser/services/{id}/{version}/entity-map
 ```
 
-When a domain or service has entities assigned, an **Entity Map** link appears automatically in the resource sidebar under the visualizer section.
+When a domain or service has entities assigned, an **Entity Diagram** link appears automatically in the **Architecture** section of the resource sidebar.
 
 ## Embed the entity map on a page
 

package/dist/docs/development/guides/domains/04-add-resources-to-domains/06-domain-resources-page.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 6
+keywords:
+  - EventCatalog domains
+  - Domain resources
+  - Resources page
+sidebar_label: Domain resources page
+title: Domain resources page
+description: See every subdomain, system, service, message, and decision record attached to a domain in one table.
+---
+
+Every domain with resources gets a **Resources** page that lists them in one table. Open it from **Quick Reference** > **Resources** in the domain's sidebar, or go to:
+
+```txt
+/docs/domains/{domain-id}/{version}/resources
+```
+
+## What the page lists
+
+The page lists the resources attached directly to the domain. Resources inside a child system or subdomain are listed on that system's or subdomain's own Resources page.
+
+| Resource | Where it comes from | Relationship |
+|----------|---------------------|--------------|
+| Subdomains | The domain's [`domains`](/docs/development/guides/domains/reference#domains) | **Contains** |
+| Systems | The domain's [`systems`](/docs/development/guides/domains/reference#systems) | **Contains** |
+| Agents | The domain's [`agents`](/docs/development/guides/domains/reference#agents) | **Contains** |
+| Data products | The domain's [`data-products`](/docs/development/guides/domains/reference#data-products) | **Contains** |
+| Services | The domain's [`services`](/docs/development/guides/domains/reference#services) | **Contains** |
+| Flows | The domain's [`flows`](/docs/development/guides/domains/reference#flows) | **Contains** |
+| Entities | The domain's [`entities`](/docs/development/guides/domains/reference#entities) | **Owns** |
+| Events, commands and queries | The domain's [`sends`](/docs/development/guides/domains/reference#sends) and [`receives`](/docs/development/guides/domains/reference#receives) | **Sends**, **Receives** or **Sends & receives** |
+| Decision records | Any ADR whose `appliesTo` includes the domain ([add ADRs to resources](/docs/development/guides/resources/adrs/linking-resources)) | **Governed by** |
+
+The **Resources** link only shows in the sidebar when the domain has at least one resource to list.
+
+The table has the same filters, sorting and row actions as the service Resources page. See [Service resources page](/docs/development/guides/resources/services/resources-page).
+
+:::info Changed in EventCatalog v5
+The sidebar link was called **Domain Resources** and is now **Resources**. The page now lists decision records and has a **Relationship** column. The domain architecture overview page (`/architecture/domains/{domain-id}/{version}`) is removed. Old links redirect to the Resources page, or to the domain's docs page when it has nothing to list.
+:::

package/dist/docs/development/guides/domains/06-visualize-domains/01-domain-diagram.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 1
+keywords:
+- domain diagram
+- domains
+- EventCatalog visualizer
+- cross-domain communication
+sidebar_label: Domain diagram
+title: Domain diagram
+description: Visualize a domain, its systems, and the domains it talks to, from a high-level overview down to messages and channels.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.0.0" />
+
+Every domain has a **Diagram** page. It shows the domain at three levels of detail, from the other domains it talks to down to the messages and channels its services send and receive.
+
+Open it from **Diagram** in the **Architecture** section of the domain sidebar, or at:
+
+```txt
+/visualiser/domains/{domain-id}/{version}
+```
+
+![Payments domain diagram at level 1, showing its systems and the domains they talk to](./img/domain-diagram-l1.png)
+
+## Levels
+
+Switch levels with **L1**, **L2** and **L3** in the canvas toolbar at the bottom of the diagram.
+
+| Level | What it shows |
+|-------|---------------|
+| **L1** | The domain with its systems and subdomains, and the other domains they send messages to or receive messages from. |
+| **L2** | Expands the systems into their services and data stores, and how they connect. |
+| **L3** | Adds the messages and channels. |
+
+![Payments domain diagram at level 2, with its systems expanded into services and data stores](./img/domain-diagram-l2.png)
+
+The page opens at level 1. The level is kept in the URL, so a shared link opens at the same level. Use `?level=` to open a level directly:
+
+```txt
+/visualiser/domains/Payments/1.0.0?level=2
+```
+
+### How resources are placed
+
+- Subdomains are shown as domains inside the domain, with their own systems and services. At L1, a subdomain without systems is a single card.
+- Other domains' subdomains are shown inside a box for their parent domain.
+- Services that are not in a system are shown with the resources they connect to.
+- Messages and channels that only other domains send through are placed outside the domain.
+- A domain without systems or subdomains opens at L2, and L1 is greyed out.
+
+## Highlight cross-domain communication
+
+When the diagram includes other domains, the canvas toolbar has a **Highlight cross-domain communication** button. It picks out the edges to and from other domains on the level you are viewing. It doesn't change the level.
+
+Use it to find where a domain depends on other domains, and which messages cross the domain boundary.
+
+The canvas toolbar and menu also let you simulate messages, hide messages or channels, and hide resource types from the legend. See [NodeGraph interactive controls](/docs/development/components/components/nodegraph#interactive-controls).
+
+## Show the diagram on the domain page
+
+Add `<NodeGraph />` to a domain page to embed its diagram. It opens at level 1.
+
+```md title="/domains/Payments/index.mdx"
+---
+id: Payments
+name: Payments
+version: 1.0.0
+---
+
+## Architecture
+
+<NodeGraph />
+```
+
+Learn more in the [NodeGraph component](/docs/development/components/components/nodegraph) docs.
+
+## Turn off the diagram
+
+Domains with [`visualiser: false`](/docs/development/guides/domains/reference#visualiser) in their frontmatter don't get a Diagram page.
+
+:::info Changed in EventCatalog v5
+The domain's **System Diagram** and **Resource Diagram** pages are replaced by the single **Diagram** page. The old System Diagram route (`/visualiser/domains/{domain-id}/{version}/systems-context`) redirects to level 1.
+
+The Domain Integration Map (`/visualiser/domain-integrations`) is removed. Level 1 of each domain's diagram shows how it integrates with other domains.
+
+Layouts saved in dev mode for a domain's old Resource Diagram don't carry over to the new page. Save the layout again if you need it.
+:::

package/dist/docs/development/guides/domains/06-visualize-domains/_category_.json

@@ -1,12 +1,11 @@
 {
   "label": "Visualize domains",
   "position": 6,
-  "className": "hidden",
   "collapsible": true,
   "collapsed": true,
   "link": {
     "type": "generated-index",
     "slug": "/domains/visualize-domains",
-    "description": "Visualize domain relationships, integrations, and entities."
+    "description": "Visualize a domain, its systems, and how it integrates with other domains."
   }
 }

package/dist/docs/development/guides/domains/09-reference.md

@@ -37,11 +37,11 @@ Ubiquitous language for a domain is documented in a sidecar file:
 | Route | Description |
 |-------|-------------|
 | `/docs/domains/{domain-id}/{version}` | Domain documentation page. |
+| `/docs/domains/{domain-id}/{version}/resources` | [Resources page](/docs/development/guides/domains/add-resources-to-domains/domain-resources-page) listing the resources attached to the domain. |
 | `/docs/domains/{domain-id}/language` | Ubiquitous language dictionary. |
 | `/docs/domains/{domain-id}/language/{term-id}` | Ubiquitous language term page. |
-| `/visualiser/domains/{domain-id}/{version}` | Domain resource diagram. |
-| `/visualiser/domains/{domain-id}/{version}/systems-context` | System context map for systems inside a domain. |
-| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity map for entities inside a domain. |
+| `/visualiser/domains/{domain-id}/{version}` | [Domain diagram](/docs/development/guides/domains/visualize-domains/domain-diagram), with levels L1 to L3. Add `?level=1`, `?level=2` or `?level=3` to open a level directly. |
+| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity Diagram for entities inside a domain. |
 
 ## Frontmatter example
 
@@ -199,7 +199,7 @@ domains:
 
 ### `systems` {#systems}
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 An array of [system](/docs/development/guides/systems/introduction) ids that belong to this domain.
 

package/dist/docs/development/guides/owners/automated-teams-and-users/create-your-own-connector.md

@@ -10,9 +10,7 @@ description: Build a custom directory connector to sync users and teams from any
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-<PlanBanner plan="Scale" />
 <AddedIn version="3.44.0" pkg="@eventcatalog/connectors" />
 
 Connectors are how EventCatalog imports and syncs users and teams from an external source so you can assign them as owners on resources in your catalog. EventCatalog ships with built-in connectors (such as [Sync from GitHub](/docs/development/guides/owners/sync-from-github) and [Sync from Microsoft Entra ID](/docs/development/guides/owners/sync-from-microsoft-entra)), but if your team uses a different system &mdash; an internal HR tool, an LDAP directory, a SaaS like Okta, or anything else &mdash; you can write your own connector with a small amount of custom code.

package/dist/docs/development/guides/owners/automated-teams-and-users/sync-from-github.md

@@ -11,9 +11,6 @@ description: Sync GitHub organization teams and members into EventCatalog as use
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
-
-<PlanBanner plan="Scale" />
 
 In EventCatalog, you can import and sync your users and teams directly from GitHub. Instead of adding people and teams by hand, you point EventCatalog at your GitHub organization and the catalog stays in sync with it automatically. Once synced, your GitHub teams and users can be assigned as owners on any resource in the catalog (services, events, domains, and more).
 

package/dist/docs/development/guides/owners/automated-teams-and-users/sync-from-microsoft-entra.md

@@ -12,9 +12,7 @@ description: Sync Microsoft Entra ID groups and direct members into EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-<PlanBanner plan="Scale" />
 <AddedIn version="3.45.0" pkg="@eventcatalog/connectors" />
 
 In EventCatalog, you can import and sync your users and teams directly from Microsoft Entra ID. Instead of adding people and teams by hand, you point EventCatalog at selected Entra groups and the catalog keeps those teams and their direct members in sync.

package/dist/docs/development/guides/resources/adrs/03-linking-resources.md

@@ -50,3 +50,11 @@ appliesTo:
 When a resource has one or more ADRs linked via `appliesTo`, a **Decision Records** group appears in that resource's sidebar. Each linked ADR shows its name and links directly to the decision page.
 
 This means engineers reading a service or event page can immediately see which architectural choices affect it, without leaving the page.
+
+### On the Resources page
+
+<AddedIn version="5.0.0" />
+
+Linked ADRs are also listed on the resource's **Resources** page (**Quick Reference** > **Resources** in the sidebar), with the relationship **Governed by**. When the page lists other kinds of resource too, use the **Decision Records** filter to show only the ADRs. This works for domains, systems, services, flows, channels, events, commands and queries.
+
+See the [service Resources page](/docs/development/guides/resources/services/resources-page) for how the page works.

package/dist/docs/development/guides/resources/adrs/06-reference.md

@@ -70,13 +70,11 @@ version: 1.0.0
 ---
 ```
 
-## Optional fields
-
 ### `status` {#status}
 
 - Type: `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded`
 
-Lifecycle status for the decision.
+Lifecycle status for the decision. EventCatalog groups ADRs by status in the sidebar and shows it on the ADR's page.
 
 ```md title="Example"
 ---
@@ -88,7 +86,7 @@ status: accepted
 
 - Type: `date`
 
-Date the decision was created or recorded.
+Date the decision was created or recorded. EventCatalog shows it on the ADR's page and sorts ADRs by it.
 
 ```md title="Example"
 ---
@@ -96,6 +94,8 @@ date: 2026-06-01
 ---
 ```
 
+## Optional fields
+
 ### `summary` {#summary}
 
 - Type: `string`

package/dist/docs/development/guides/resources/agents/11-reference.md

@@ -30,7 +30,7 @@ Versioned agents use:
 | Route | Description |
 |-------|-------------|
 | `/docs/agents/{agent-id}/{version}` | Agent documentation page. |
-| `/visualiser/agents/{agent-id}/{version}` | Agent resource diagram. |
+| `/visualiser/agents/{agent-id}/{version}` | Agent diagram (**Diagram** in the sidebar). |
 
 ## Required fields
 

package/dist/docs/development/guides/resources/data/04-reference.md

@@ -30,7 +30,7 @@ Versioned data stores use:
 | Route | Description |
 |-------|-------------|
 | `/docs/containers/{container-id}/{version}` | Data store documentation page. |
-| `/visualiser/containers/{container-id}/{version}` | Data store resource diagram. |
+| `/visualiser/containers/{container-id}/{version}` | Data store diagram (**Diagram** in the sidebar). |
 
 ## Required fields
 

package/dist/docs/development/guides/resources/data-products/07-reference.md

@@ -29,7 +29,7 @@ Versioned data products use:
 | Route | Description |
 |-------|-------------|
 | `/docs/data-products/{data-product-id}/{version}` | Data product documentation page. |
-| `/visualiser/data-products/{data-product-id}/{version}` | Data product resource diagram. |
+| `/visualiser/data-products/{data-product-id}/{version}` | Data product diagram (**Diagram** in the sidebar). |
 
 ## Required fields
 

package/dist/docs/development/guides/resources/entities/05-entity-maps.md

@@ -30,7 +30,7 @@ Domains and services have dedicated entity map routes:
 /visualiser/services/{id}/{version}/entity-map
 ```
 
-When a domain or service has entities assigned, an **Entity Map** link appears automatically in the resource sidebar under the visualizer section.
+When a domain or service has entities assigned, an **Entity Diagram** link appears automatically in the **Architecture** section of the resource sidebar.
 
 ## Embed an entity map
 

package/dist/docs/development/guides/resources/entities/06-reference.md

@@ -41,8 +41,8 @@ Nested entities use the same `versioned/{version}/index.mdx` pattern inside thei
 |-------|-------------|
 | `/docs/entities/{entity-id}/{version}` | Entity documentation page. |
 | `/visualiser/entities/{entity-id}/{version}` | Entity resource diagram. |
-| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity map for entities assigned to a domain. |
-| `/visualiser/services/{service-id}/{version}/entity-map` | Entity map for entities assigned to a service. |
+| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity Diagram for entities assigned to a domain. |
+| `/visualiser/services/{service-id}/{version}/entity-map` | Entity Diagram for entities assigned to a service. |
 
 ## Frontmatter example
 

package/dist/docs/development/guides/resources/flows/01-introduction.md

@@ -14,10 +14,20 @@ Flows are a way to document business workflows in your organization. Flows help
 
 An example of a flow could be user purchasing a product in an e-commerce store. They start by logging into a service, getting onboarded and purchasing something from a business. Across this journey may applications, databases, interactions are happening. Flows let you capture these.
 
-You can reuse your documented resources (e.g services, messages, data stores, data products) in your flows.
+You can reuse your documented resources (e.g services, messages, channels, data stores, data products) in your flows.
 
 ![Example](../../img/flows/flow-example.png)
 
+## Explore a flow
+
+Each flow gets a diagram you can explore:
+
+- **Group by** domain, system or team to see which parts of your architecture each step belongs to.
+- **Walk through** the flow one step at a time, choosing the way on at each branch.
+- Open the flow's **Resources** page from **Quick Reference** in the sidebar to see the services, messages, agents, data stores, data products and sub-flows its steps use.
+
+See [Explore flows](/docs/development/guides/resources/flows/explore-flows) for details.
+
 <!-- [You can see a payment flow example here](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0). -->
 
 

package/dist/docs/development/guides/resources/flows/03-model-flow-steps.md

@@ -13,7 +13,7 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 Nodes are the building blocks of flows. They are used to represent the different steps in a flow.
 
-With flow nodes you can reference your services, events, commands and queries, external services, users (actors), data stores, data products, or create your own custom nodes.
+With flow nodes you can reference your services, events, commands and queries, channels, external services, users (actors), data stores, data products, or create your own custom nodes.
 
 ## Common step properties
 
@@ -22,16 +22,47 @@ Every flow step (regardless of node type) supports these properties:
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
 | `id` | `string \| number` | **Yes** | Unique identifier for the step |
-| `title` | `string` | **Yes** | The label displayed on the node in the flow diagram |
+| `title` | `string` | No | The label displayed on the node in the flow diagram. Defaults to the name of the resource the step references, the actor's, external system's or custom node's name, or the step's `id` (optional since 5.0.0) |
 | `summary` | `string` | No | A short description shown in the node sidebar |
-| `type` | `"node" \| "message" \| "user" \| "actor"` | No | Hint for how the node should be rendered |
+| `type` | `string` | No | Accepted but ignored. The node type comes from the node type property the step uses (see [Flow node types](#flow-node-types)) |
 | `next_step` | [Step reference](#connecting-steps) | No | The next step in the flow (cannot be used with `next_steps`) |
 | `next_steps` | [Step reference](#connecting-steps)[] | No | Multiple next steps for branching (cannot be used with `next_step`) |
+| `x-*` | any | No | Your own metadata. Custom step properties must start with `x-` |
 
 :::tip Type exclusivity rule
-Each step can only use **one** node type property. You cannot combine `message`, `service`, `flow`, `container`, `dataProduct`, `actor`, `custom`, or `externalSystem` on the same step.
+Each step can only use **one** node type property. You cannot combine `message`, `service`, `agent`, `channel`, `flow`, `container`, `dataProduct`, `actor`, `custom`, or `externalSystem` on the same step. From 5.0.0, a step that uses two node types fails the build (see [Mistakes in flow steps](#mistakes-in-flow-steps)).
 :::
 
+## Mistakes in flow steps {#mistakes-in-flow-steps}
+
+<AddedIn version="5.0.0" />
+
+EventCatalog checks your flow steps when it builds, so mistakes don't fail silently.
+
+These fail the build, with a message naming the step and what to change:
+
+- **Unknown step properties**, such as a typo like `servce:`. Custom properties must start with `x-` (for example `x-runbook`).
+- **A step that uses two node types**, for example `message` and `service` on the same step. Split it into two steps.
+- **A step that uses both `next_step` and `next_steps`**. Use `next_step` for one next step, or `next_steps` for several.
+
+```txt
+Step "checkout" points at message and service. A step can only be one thing, so split it into two steps.
+Step "checkout" has both next_step and next_steps. Use next_step for one next step, or next_steps for several.
+Unknown property "servce". Custom properties must start with "x-".
+```
+
+These log a warning naming the flow and step, and the build carries on:
+
+- **A `next_step` or `next_steps` entry that points at a step id that isn't in the flow.** The arrow is left out.
+- **A reference to a resource that isn't in the catalog** (for example a renamed service). The step is shown as a plain step.
+
+```txt
+[flows] Flow "Checkout" (1.0.0): step "start" leads to step "paymnet", but the flow has no step with that id.
+[flows] Flow "Checkout" (1.0.0): step "start" points at service "OrderServce" (latest), which is not in the catalog, so it is shown as a plain step.
+```
+
+To catch these before you build, run the [EventCatalog Linter](/docs/development/developer-tools/eventcatalog-linter/reference/rules). It reports the same mistakes, including next steps that aren't in the flow (`refs/flow-step-exists`).
+
 ## Connecting steps {#connecting-steps}
 
 Use `next_step` or `next_steps` (not both) to connect steps together.
@@ -63,6 +94,7 @@ next_steps:
 - [actor](#actor) — Represents a person in your flow diagram
 - [externalSystem](#externalsystem) — Represents an external system in your flow diagram
 - [message](#message) — Represents an event, command or query resource in EventCatalog
+- [channel](#channel) — Represents a channel resource in EventCatalog (added in EventCatalog 5.0.0)
 - [service](#service) — Represents a service resource in EventCatalog
 - [agent](#agent) — Represents an agent resource in EventCatalog (added in EventCatalog 3.41.0)
 - [flow](#flow) — Represents a flow in EventCatalog (added in EventCatalog 2.34.2)
@@ -73,7 +105,7 @@ next_steps:
 
 ### default node type {#default}
 
-A blank node type with just a title in your flow. No additional properties are needed beyond the [common step properties](#common-step-properties).
+A blank node type with just a title in your flow. No additional properties are needed beyond the [common step properties](#common-step-properties). If you leave out `title`, the node shows the step's `id`.
 
 ```yml
 steps:
@@ -151,6 +183,33 @@ steps:
 
 ---
 
+### channel {#channel}
+
+<AddedIn version="5.0.0" />
+
+Represents and refers to a [channel](/docs/development/guides/resources/messages/message-channels/introduction) resource in EventCatalog. The step renders as a channel node that links to the channel's docs.
+
+#### Channel properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the channel in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "orders_topic"
+    title: "Orders topic"
+    channel:
+      id: "orders"
+      version: "1.0.0"
+    next_step:
+      id: "inventory_service"
+      label: "Deliver to subscribers"
+```
+
+---
+
 ### service
 
 Represents and refers to a service resource in EventCatalog.
@@ -308,7 +367,7 @@ You can view a UI example of a custom nodes [here](https://demo.eventcatalog.dev
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `title` | `string` | **Yes** | The title shown on the node |
+| `title` | `string` | No | The title shown on the node. Defaults to the step's `title` (required before 5.0.0) |
 | `icon` | `string` | No | Icon shown on the node (see [Heroicons](https://heroicons.com/) for the list of icons) |
 | `type` | `string` | No | A type label shown on the sidebar of the node (e.g. "Scheduler", "Database") |
 | `summary` | `string` | No | A short description of the node |

package/dist/docs/development/guides/resources/flows/05-explore-flows.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog flows
+- Flow diagram
+- Group by
+- Swimlanes
+sidebar_label: Explore flows
+title: Explore flows
+description: Group a flow's steps by domain, system or team, walk through a flow step by step, and see the resources a flow uses.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Every flow has a diagram. Open it from **Architecture** > **Flow Diagram** in the flow's sidebar, or go to `/visualiser/flows/{flow-id}/{version}`. The same diagram renders on the flow's docs page.
+
+From the diagram you can group the steps by who owns them, walk through the flow one step at a time, and open the resources the flow uses.
+
+![Place an Order flow grouped by system, with the Group by menu open and the walkthrough card in the bottom left](./img/flow-group-by.png)
+
+:::info Flows don't use levels
+Other diagrams have L1, L2 and L3 levels in the canvas toolbar. Flow diagrams don't have levels. Use **Group by** to see where the steps sit in your architecture.
+:::
+
+## Group steps by domain, system or team
+
+<AddedIn version="5.0.0" />
+
+Use **Group by** in the top right of the diagram, or press <kbd>G</kbd>, to group the flow's steps:
+
+| Option | What it does |
+|--------|--------------|
+| **Nothing** | No groups (the default). |
+| **Domain** | One group per domain. |
+| **System** | One group per system. |
+| **Team** | One group per owning team. |
+| **Domain, then system** | Systems nested inside their domain. |
+
+Each option shows how many groups it makes (for example "3 systems"). The menu only lists options the flow has groups for.
+
+Under **Show groups as**, choose how the groups are drawn:
+
+- **Boxes**: a box around each group's steps. This is the default.
+- **Lanes**: full-width lanes stacked top to bottom, with the group's name down the left-hand side.
+
+Lanes don't nest, so **Domain, then system** always uses boxes. If you pick **Lanes** with it, the flow is grouped by domain only.
+
+To stop grouping, click the **×** next to **Group by**, or choose **Nothing**.
+
+### Where the groups come from
+
+You don't need to change your flows to group them. EventCatalog works out each step's group from your catalog:
+
+| Step | Group |
+|------|-------|
+| Services, agents, data stores and data products | The domain and system they belong to, and their owning team. A resource listed by a domain directly belongs to that domain, otherwise it belongs to the domain of its system. |
+| Systems | That system, and the domain that lists it. |
+| Messages, channels, custom steps and sub-flows | The group of the step before them. A step at the start of the flow takes the group of the step it leads to. |
+| Actors and external systems | A group of their own, named **External**. |
+
+The team group comes from the resource's `owners`. When a resource has several owners, a team wins over a user. Hidden teams and users are left out.
+
+Steps that don't belong to any group sit outside the boxes. With lanes, they go in a lane named after what's missing, for example **No system**.
+
+### Share a grouped flow
+
+The grouping is kept in the URL, so a link opens the flow grouped the same way:
+
+```txt
+/visualiser/flows/place-an-order/1.0.0?group=system&groupStyle=boxes
+```
+
+| Parameter | Values |
+|-----------|--------|
+| `group` | `domain`, `system`, `team`, `domain-system` |
+| `groupStyle` | `boxes`, `lanes` |
+
+To embed a flow that starts grouped, use the [`lanes` prop on the `<Flow />` component](/docs/development/components/components/flow), for example `<Flow id="place-an-order" lanes="team" />`.
+
+### What changes while a flow is grouped
+
+- **Save Layout** is hidden in dev mode, because grouped steps are placed inside their groups. Stop grouping to save a layout.
+- **Copy as mermaid** and **Render as mermaid** leave the groups out.
+- Sub-flows can't be expanded inline.
+
+## Walk through a flow
+
+The walkthrough card in the bottom left of the diagram steps through the flow one hop at a time. It names the step the flow starts at and how many steps the flow has.
+
+1. Click **Start** on the **Walk through this flow** card. The walkthrough starts at the first step.
+2. Click **Next**, or press <kbd>→</kbd>, to move to the next step. Click **Back**, or press <kbd>←</kbd>, to go back.
+3. At a branch, pick the way on from the dropdown (or press its number, <kbd>1</kbd> to <kbd>9</kbd>), then click **Next**.
+4. At the end of the flow, click **Restart** to walk through again, or **Finish** to see the whole flow. Press <kbd>Esc</kbd> at any time to stop.
+
+While you walk through:
+
+- The steps you've walked are numbered, and the current step is ringed.
+- The card shows the current step's type, title and summary. Click **More** to read a long summary in full.
+- Click the link icon on the card to open the current step's docs.
+- If you change the grouping, the walkthrough carries on from the same step.
+
+The walkthrough shows on the flow's diagram page and docs page. On a [`<Flow />` embed](/docs/development/components/components/flow), turn it on with `walkthrough={true}`.
+
+## See the resources a flow uses
+
+<AddedIn version="5.0.0" />
+
+Every flow that references catalog resources gets a **Resources** page. Open it from **Quick Reference** > **Resources** in the flow's sidebar, or go to `/docs/flows/{flow-id}/{version}/resources`.
+
+The page lists the services, messages (events, commands and queries), agents, data stores, data products and sub-flows the flow's steps use, and the decision records (ADRs) that apply to the flow. Use the filters to narrow the list by type, or search by name.
+
+The **Resources** link only shows in the sidebar when the flow has at least one resource to list.