@eventcatalog/core 4.2.3 → 4.2.4

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-WOASLQ3F.js";
-import "../chunk-DGDCWOWP.js";
+} from "../chunk-BXEGST4Z.js";
+import "../chunk-J2MVHSKA.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-QQC5UX3E.js";
+} from "../chunk-GCEFDCZB.js";
 import "../chunk-K2XIENVT.js";
-import "../chunk-WOASLQ3F.js";
-import "../chunk-DGDCWOWP.js";
+import "../chunk-BXEGST4Z.js";
+import "../chunk-J2MVHSKA.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-M2YEUPPP.js → chunk-5MIGBCON.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DGDCWOWP.js";
+} from "./chunk-J2MVHSKA.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-WOASLQ3F.js → chunk-BXEGST4Z.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DGDCWOWP.js";
+} from "./chunk-J2MVHSKA.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-QQC5UX3E.js → chunk-GCEFDCZB.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-K2XIENVT.js";
 import {
   raiseEvent
-} from "./chunk-WOASLQ3F.js";
+} from "./chunk-BXEGST4Z.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/{chunk-DGDCWOWP.js → chunk-J2MVHSKA.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-I4TTHHXI.js → chunk-WVIOZDVK.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-M2YEUPPP.js";
+} from "./chunk-5MIGBCON.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DGDCWOWP.js";
+} from "./chunk-J2MVHSKA.js";
 export {
   VERSION
 };

package/dist/docs/development/00-why-eventcatalog.md

@@ -18,33 +18,33 @@ As systems grow, complexity grows. Documentation becomes important for teams but
 
 ### What is EventCatalog?
 
-EventCatalog is a documentation and governance tool that is built for architects.
+EventCatalog is an open source documentation tool that is built for software architecture.
 
- It lets you document and visualize your architecture with primitives you are already familiar with. You can document domains, systems, applications and schemas and visualize how they all relate to each other.
+We focus on architecture primitives like domains, systems and resources (e.g services, messages) and let you document your architecture with primitives you are already familiar with. 
 
 EventCatalog creates an internal architecture graph of how your systems work. This makes EventCatalog accessible to your AI agents, LLMs and AI workflows and [creates context of your business and architecture](/docs/development/ask-your-architecture/intro).
 
-EventCatalog is technology agnostic, this means you can document and model any systems you have
+EventCatalog is technology agnostic, this means you can document and model any systems you have.
 
 
-#### What can EventCatalog do for you?
+#### Our project goals for you
 
-- **Save time across the organization**
+- **Help you save time across the organization**
   - Help teams find information they need across your business and organization
   - Document high level information for stakeholders while providing lower level details to your teams.
   - Connect to your AI Agents and AI Workflows. Give your LLMs the context they need.
-- **Create documentation you can trust**
+- **Create a documentation solution you can trust**
   - Sync documentation from your code with our Agent
   - Automate documentation from your OpenAPI, AsyncAPI, or schema registries
   - Use EventCatalog Agent to sync code to docs from your CI/CD workflows.
   - Write your own automation and plugins with the [EventCatalog SDK](/docs/sdk)
-- **Detect breaking changes before they reach production**
+- **Help you detect breaking changes before they reach production**
   - Use EventCatalog Agent to detect breaking schema changes
   - Bring your own model and get notified when things break
 - **Use natural langugage to query your architecture**
   - Connect AI tools to your architecture using [EventCatalog's MCP server](/docs/development/ask-your-architecture/mcp-server/introduction)
   - Ask architectural questions grounded in your documented domains, services, events, data products, and schemas
-- **Show the bigger picture**
+- **Help your teams understand the bigger picture**
   - Help business stakeholders understand the bigger picture
   - Visualize your architecture and future ideas
   - Document key business workflows

package/dist/docs/development/01-fundamentals.md

@@ -8,27 +8,28 @@ title: Fundamentals
 description: Understanding the fundamentals of EventCatalog
 ---
 
-EventCatalog is a architecture catalog built around software primitives and domain-driven design patterns, so you can model the systems you actually build instead of creating disconnected documentation pages.
+EventCatalog is a self hosted [open source documentation tool](https://github.com/event-catalog/eventcatalog/stargazers) for software architecture. It allows you to document your architecture using software primitives and patterns such as domains, systems and resources rather than random documentation pages (e.g Confluence).
 
-EventCatalog gives your teams and AI agents a shared understanding of how your systems work across your organization.
+EventCatalog follows the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) pattern. Your documentation is stored in code using [markdown (MDX)](https://mdxjs.com/) and stays private, in your own repository and infrastructure. 
 
-EventCatalog is an open source project and is self-hosted and follows the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) pattern. All pages in EventCatalog are powered by [markdown (MDX)](https://mdxjs.com/).
+At its core, EventCatalog gives you a small set of building blocks for your documentation.
 
-Your catalog is private, stays in your own repository and infrastructure. 
-
-At its core, EventCatalog gives you a small set of building blocks.
+![EventCatalog model showing domains, systems, resources, contracts, and ownership](./img/levels-catalog.png)
 
 - **Domains (Level 1)** - a domain describes a business boundary
 - **Systems (Level 2)** - a system is a collection of resources that work together to perform a function.
 - **Resources (Level 3)** - individual resources (e.g services, messages, data stores) that can be assigned to systems or domains.
 
-All building blocks are optional, it's up to you how you want to model your architecture in your catalog.
+:::info What blocks to use?
+All building blocks are optional in your catalog. It's up to you how you want to model your documentation.
 
-![EventCatalog model showing domains, systems, resources, contracts, and ownership](./img/ec-types.png)
+Want to match your c4 model?, you can. Want to document a monolith you can. Want to document distributed systems you can.
+We focus on architecture primitives and let you fill in the details.
+:::
 
 ## The EventCatalog model
 
-Domains give your catalog a business shape. They help users understand the boundaries in your architecture, such as `Shopping`, `Payments`, `Fulfilment`, or `Customer`.
+Domains describe a business capability or boundary. They help users understand the boundaries in your architecture, such as `Shopping`, `Payments`, `Fulfilment`, or `Customer`.
 
 Systems give your catalog an operating shape. A system is a collection of resources that work together to perform a function. For example, a `Shopping` domain might contain a `Cart System` and a `Promotion System`.
 
@@ -48,7 +49,9 @@ Teams and users can own domains, systems, resources, and contracts. This makes o
 
 ## Levels of detail
 
-EventCatalog is useful to anyone in your organization. You can define high level primitives whilst giving lower level implementation details.
+Architecture documentation all have different audiences, and EventCatalog can be useful to anyone in your organization.
+
+You can define a high level of information for stakeholders whilst whilst giving lower level implementation details for developers.
 
 | Level | Name | What it answers | Example |
 |-------|------|-----------------|---------|
@@ -76,9 +79,9 @@ It's up to you where you define your catalog (or catalogs). Here are some exampl
 | **Federated** | Multiple EventCatalog instances connected into one view |
 
 
-## Automation
+## Living documentation
 
-Your documentation can also be automated, keeping your implementation details close to your documentation. There are many [integrations](/integrations) or you can create your own automations with our [SDK](/docs/sdk).
+Your documentation can also be automated, keeping your implementation details close to your documentation. There are many [integrations](/integrations) or you can create your own automations with our [SDK](/docs/sdk). We also have started building some [AI Agents to help you manage your documentation](https://github.com/event-catalog/agents) in CI/CD environments.
 
 ## Visual editing
 

package/dist/docs/development/bring-your-own-documentation/diagrams/07-reference.md

@@ -142,3 +142,7 @@ attachments:
 ## Content
 
 Diagram pages can contain any MDX supported by EventCatalog, including Mermaid, PlantUML, Miro, IcePanel, Lucid, Draw.io, FigJam, images, and normal markdown.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/components/components/07-custom-properties.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 7
+keywords:
+- components
+- custom properties
+- resource metadata
+sidebar_label: CustomProperties
+title: CustomProperties
+description: Render custom x-* resource properties in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.3.0" />
+
+`<CustomProperties />` and `<CustomProperty />` render organization-specific `x-*` properties from the current resource.
+
+Both are built-in components, so you can use them in resource MDX without importing them.
+
+Read [Custom properties on resources](/docs/development/customization/custom-properties) to learn how to define `x-*` properties and reference them from MDX or your own components.
+
+## Render all custom properties
+
+Add custom properties to the resource frontmatter, then add `<CustomProperties />` to its Markdown content.
+
+```jsx title="/adrs/adr-001-use-transactional-outbox/index.mdx"
+---
+id: adr-001-use-transactional-outbox
+name: 'ADR-001: Publish product events via a transactional outbox'
+version: 1.0.0
+status: accepted
+date: 2026-02-10
+x-next-review-date: '2027-02-10'
+x-risk-level: medium
+---
+
+## Context
+
+The Product Catalog System publishes product changes through a transactional outbox.
+
+<CustomProperties title="Review metadata" />
+```
+
+### Output
+
+![CustomProperties rendering review metadata on an architecture decision record](/img/docs/components/custom-properties.png)
+
+Property names are converted into readable labels. For example, `x-next-review-date` is displayed as **Next Review Date**. The information icon beside each label shows the original `x-*` property name.
+
+Strings, numbers, and booleans are rendered directly. Arrays are rendered as bullet lists, and nested objects are rendered recursively as grouped values.
+
+### CustomProperties props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `Custom properties` | Heading displayed above the properties table. Pass an empty string to hide the heading. |
+
+## Render one custom property
+
+Use `<CustomProperty />` when you only want to render one `x-*` value.
+
+```mdx
+<CustomProperty name="x-risk-level" />
+```
+
+Use `label` to override the generated property label.
+
+```mdx
+<CustomProperty name="x-next-review-date" label="Review again on" />
+```
+
+If the named property is not defined on the current resource, the component renders nothing.
+
+### CustomProperty props
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | Yes | Name of the `x-*` property to render. |
+| `label` | `string` | No | Label displayed for the property. By default, EventCatalog generates a label from `name`. |
+
+## Support
+
+`<CustomProperties />` and `<CustomProperty />` are supported on domains, systems, services, agents, events, commands, queries, channels, flows, containers, entities, data products, diagrams, and ADRs.
+
+The components require an `.mdx` resource file. Plain `.md` files do not evaluate MDX components.

package/dist/docs/development/components/components/{07-design.md → 08-design.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 keywords:
 - components
 - remote schema

package/dist/docs/development/components/components/{08-entitymap.md → 09-entitymap.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 keywords:
 - components
 sidebar_label: EntityMap
@@ -68,4 +68,4 @@ If you want to render a subset of the entities in the map, you can use the `enti
 
 In this example, only the `Order` and `Customer` entities will be chosen to be rendered in the map.
 
-If the `Order` or `Customer` entity references other entities, they will also be rendered in the map
+If the `Order` or `Customer` entity references other entities, they will also be rendered in the map

package/dist/docs/development/components/components/{09-flow.md → 10-flow.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 keywords:
 - components
 sidebar_label: Flow

package/dist/docs/development/components/components/{10-link.md → 11-link.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 keywords:
 - components
 sidebar_label: Link

package/dist/docs/development/components/components/{11-mermaid-file-loader.md → 12-mermaid-file-loader.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 12
 keywords:
 - components
 - remote schema

package/dist/docs/development/components/components/{12-message-table.md → 13-message-table.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 13
 keywords:
 - components
 sidebar_label: MessageTable

package/dist/docs/development/components/components/{13-nodegraph.md → 14-nodegraph.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 13
+sidebar_position: 14
 keywords:
 - components
 sidebar_label: NodeGraph
@@ -167,4 +167,3 @@ You can see a demo of this [here](https://demo.eventcatalog.dev/docs/domains/E-C
 
 
 
-

package/dist/docs/development/components/components/{14-openapi.md → 15-openapi.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 15
 keywords:
 - components
 sidebar_label: OpenAPI

package/dist/docs/development/components/components/{15-prompt.md → 16-prompt.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 16
 keywords:
   - components
   - prompt

package/dist/docs/development/components/components/{16-remote-schema.md → 17-remote-schema.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 16
+sidebar_position: 17
 keywords:
 - components
 - remote schema

package/dist/docs/development/components/components/{17-resource-group-table.md → 18-resource-group-table.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 17
+sidebar_position: 18
 keywords:
 - components
 sidebar_label: ResourceGroupTable

package/dist/docs/development/components/components/{18-resource-link.md → 19-resource-link.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 18
+sidebar_position: 19
 keywords:
 - components
 sidebar_label: ResourceLink

package/dist/docs/development/components/components/{19-schema.md → 20-schema.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 19
+sidebar_position: 20
 keywords:
 - components
 sidebar_label: Schema

package/dist/docs/development/components/components/{20-schema-viewer.md → 21-schema-viewer.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 20
+sidebar_position: 21
 keywords:
 - components
 sidebar_label: SchemaViewer

package/dist/docs/development/components/components/{21-steps.md → 22-steps.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 21
+sidebar_position: 22
 keywords:
   - components
 sidebar_label: Steps

package/dist/docs/development/components/components/{22-tabs.md → 23-tabs.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 22
+sidebar_position: 23
 keywords:
   - components
 sidebar_label: Tabs

package/dist/docs/development/components/components/{23-tiles.md → 24-tiles.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 23
+sidebar_position: 24
 keywords:
   - components
 sidebar_label: Tiles

package/dist/docs/development/components/components/{24-visibility.md → 25-visibility.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 24
+sidebar_position: 25
 keywords:
   - components
   - visibility

package/dist/docs/development/customization/02-themes.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 8
 keywords:
   - EventCatalog themes
   - dark mode

package/dist/docs/development/customization/06-customize-tables.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 7
 keywords:
 - EventCatalog tables
 sidebar_label: Tables

package/dist/docs/development/customization/07-resource-icons.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 9
 keywords:
 - EventCatalog resource icons
 - custom icons

package/dist/docs/development/customization/08-custom-properties.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog custom properties
+- resource metadata
+- custom frontmatter
+sidebar_label: Resource custom properties
+title: Custom properties on resources
+description: Add organization-specific metadata to EventCatalog resources and render it in Markdown or custom components.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.2.3" />
+
+Custom properties let you add organization-specific metadata to a resource without changing EventCatalog's built-in resource model.
+
+Custom property names must:
+
+- be defined at the top level of the resource frontmatter
+- start with `x-`
+- contain at least one character after `x-`
+
+Their values can be strings, numbers, booleans, arrays, or nested objects.
+
+```markdown title="/services/PaymentAPI/index.mdx"
+---
+id: PaymentAPI
+name: Payment API
+version: 1.0.0
+summary: Authorizes and records payments.
+x-operational-tier: 1
+x-scrum-masters:
+  - David
+  - Andrew
+x-on-call:
+  schedule: payments-primary
+  escalation-channel: '#payments-incidents'
+---
+```
+
+You can add custom properties to domains, systems, services, agents, events, commands, queries, channels, flows, containers, entities, data products, diagrams, and ADRs.
+
+## Why use custom properties?
+
+EventCatalog provides first-class fields for common concepts such as owners, messages, relationships, schemas, and repositories. Custom properties are useful when your organization needs metadata that is specific to its own platform or processes.
+
+For example, you can use them to record:
+
+- operational tiers, recovery objectives, or on-call schedules
+- data classification, retention, or compliance requirements
+- internal cost centres or business capabilities
+- maturity scores or governance review dates
+- metadata consumed by generators, plugins, or custom components
+
+Custom properties are also useful when you want to introduce an internal convention gradually without requiring EventCatalog to understand or interpret the value.
+
+:::tip
+Use EventCatalog's built-in fields when they already describe the concept. Use custom properties for metadata that is specific to your organization.
+:::
+
+## Render all custom properties
+
+Add the `CustomProperties` component to the Markdown content of a resource to render every `x-*` property.
+
+`CustomProperties` and `CustomProperty` are built-in components, so you do not need to import them.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+<CustomProperties />
+```
+
+By default, the component uses **Custom properties** as its heading. Use the `title` prop to change it.
+
+```jsx
+<CustomProperties title="Operational metadata" />
+```
+
+Property names are converted into readable labels. For example, `x-operational-tier` is displayed as **Operational Tier**. The original `x-*` name is available from the information icon beside the label.
+
+Arrays are rendered as lists and nested objects are rendered as grouped values.
+
+![Custom properties rendered on an architecture decision record](/img/docs/components/custom-properties.png)
+
+These component and JavaScript expression examples require an `.mdx` resource file. Plain `.md` files do not evaluate MDX components or expressions.
+
+## Render one custom property
+
+Use `CustomProperty` when you only want to show one value.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+<CustomProperty name="x-operational-tier" />
+```
+
+You can override the generated label.
+
+```jsx
+<CustomProperty name="x-scrum-masters" label="Scrum masters" />
+```
+
+If the named property is not present on the resource, the component renders nothing.
+
+## Reference custom properties in Markdown
+
+Resource frontmatter is available through the `frontmatter` variable. Because custom property names contain hyphens, use JavaScript bracket notation.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+## Operations
+
+Operational tier: {frontmatter['x-operational-tier']}
+```
+
+Dot notation does not work:
+
+```jsx
+{/* This is interpreted as subtraction and causes a runtime error. */}
+{frontmatter.x-operational-tier}
+```
+
+Render an array by mapping over its value.
+
+```jsx
+<ul>
+  {frontmatter['x-scrum-masters']?.map((name) => (
+    <li>{name}</li>
+  ))}
+</ul>
+```
+
+Nested object values can be referenced in the same way.
+
+```jsx
+On-call schedule: {frontmatter['x-on-call'].schedule}
+```
+
+## Pass custom properties to your own components
+
+Custom components do not receive resource frontmatter automatically. Pass the values they need as props.
+
+```jsx title="/services/PaymentAPI/index.mdx"
+import OperationalMetadata from '@catalog/components/operational-metadata.astro';
+
+<OperationalMetadata
+  tier={frontmatter['x-operational-tier']}
+  scrumMasters={frontmatter['x-scrum-masters']}
+/>
+```
+
+Read those props in your Astro component.
+
+```jsx title="/components/operational-metadata.astro"
+---
+interface Props {
+  tier: number;
+  scrumMasters?: string[];
+}
+
+const { tier, scrumMasters = [] } = Astro.props;
+---
+
+<section class="not-prose">
+  <p>Operational tier: {tier}</p>
+  <ul>
+    {scrumMasters.map((name) => <li>{name}</li>)}
+  </ul>
+</section>
+```
+
+Read [Pass data into components](/docs/development/components/custom-components/pass-data-into-components) to learn more about using resource frontmatter with your own components.
+
+## Naming and security guidance
+
+- Use stable, descriptive names such as `x-operational-tier` or `x-data-classification`.
+- Consider an organization namespace, such as `x-acme-cost-centre`, when properties may be shared across tools.
+- Keep the meaning and expected value type consistent across resources.
+- Do not store secrets, credentials, or private tokens in custom properties. Resource frontmatter is catalog content and may be included in generated output.
+- Custom properties are stored and rendered, but EventCatalog does not automatically use them for relationships, diagrams, search behavior, or validation beyond the `x-*` naming requirement.

package/dist/docs/development/customization/customize-visualizer/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Customize Visualizer",
-  "position": 8,
+  "position": 10,
   "collapsible": true,
   "collapsed": true,
   "link": {

package/dist/docs/development/deployment/build-ssr-mode.md

@@ -47,4 +47,12 @@ This will output one directory
 
 You will need to deploy your EventCatalog to a server that can run Node.js.
 
-The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
+The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
+
+## Loading indicator
+
+<AddedIn version="4.2.4" />
+
+Server-side rendering means a page's render time depends on your server, so navigations can occasionally take longer than a static build.
+
+EventCatalog shows a thin progress bar at the top of the page during navigations that take longer than 200ms, so the catalog never looks unresponsive. It works automatically and needs no configuration.

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

@@ -515,3 +515,7 @@ The attachments can be a URL string or an object with additional properties.
 | `description` | `string` | No | The description of the attachment. |
 | `type` | `string` | No | The type of the attachment, used to group attachments in the UI. |
 | `icon` | `string` | No | The icon of the attachment. You can pick from the [lucide icons](https://lucide.dev/icons/) library. |
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -245,3 +245,7 @@ appliesTo:
 ```
 
 Supported resource types include `agent`, `service`, `system`, `event`, `command`, `query`, `flow`, `channel`, `domain`, `user`, `team`, `container`, `entity`, `diagram`, and `data-product`.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -236,3 +236,7 @@ tools:
     description: Retrieves order status and recent order events.
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -209,3 +209,7 @@ badges:
     textColor: green
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -199,3 +199,7 @@ outputs:
       type: avro
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -271,3 +271,7 @@ Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity
 ```
 
 This is useful when you want the documentation page to show the same properties defined in frontmatter.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

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

@@ -224,3 +224,7 @@ steps:
     next_step: submit-order
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md

@@ -4,6 +4,7 @@ keywords:
 sidebar_label: Patterns for shared messages
 title: Patterns for shared messages
 description: Understand the patterns for shared messages in EventCatalog.
+sidebar_position: 3
 ---
 
 import ProjectTree from '@site/src/components/MDX/ProjectTree';

package/dist/docs/development/guides/resources/messages/04-connect-messages/04-map-commands-to-events.md

@@ -0,0 +1,95 @@
+---
+keywords:
+- EventCatalog command events
+- command outcomes
+- map commands to events
+sidebar_label: Map commands to events
+title: Map commands to events
+description: Document which events a command can trigger, including the events produced in different scenarios.
+sidebar_position: 2
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.2.0" />
+
+Commands often produce one of several events. For example, a `CreateOrder` command may produce `OrderCreated` when it succeeds or `OrderRejected` when it fails.
+
+EventCatalog lets you document these relationships so teams can see which events to expect from a command and which commands can produce a specific event.
+
+![Cancel Order command mapped to the Order Cancelled event through the Order Service](./imgs/cancel-order-command-to-event.png)
+
+## Connect a command to events
+
+Commands are `received` from particular resources in EventCatalog (e.g services). When you receive a command, you can also specify what events are triggered downstream, you do this by using the `triggers` property.
+
+In the example below, the `OrderService` receives the `CreateOrder` (command) and we also specify that htis command is linked to and triggers the `OrderCreated` and `OrderRejected` event.
+
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+version: 1.0.0
+name: Order service
+receives:
+  # receives the CreateOrder Command
+  - id: CreateOrder
+    version: 1.0.0
+    # Tell EventCatalog that the CreateOrderCommand
+    # in this context will trigger the OrderCreated and Rejeected events.
+    triggers:
+      - id: OrderCreated
+        version: 1.0.0
+      - id: OrderRejected
+        version: 1.0.0
+---
+```
+
+The command and every event it triggers must already exist in your catalog before EventCatalog can resolve the relationship.
+
+## Describe different scenarios
+
+Add an optional `condition` to explain the scenario in which an event is produced. Conditions are useful for success and failure outcomes, business-rule branches, or different paths that produce the same event.
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+version: 1.0.0
+name: Order service
+receives:
+  - id: CreateOrder
+    version: 1.0.0
+    triggers:
+      - id: OrderCreated
+        version: 1.0.0
+        # specify the scenario when this event would be triggered
+        condition: When payment is authorized and stock is available
+---
+```
+
+This lets you document common command-handling scenarios such as:
+
+- A command producing a success event or a failure event.
+- A command producing different events based on a business rule.
+- Multiple paths producing the same event for different reasons.
+- Different services producing different events from the same command.
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `id` | `string` | Yes | Id of the event produced by the command. |
+| `version` | `string` | No | Version or semver range of the event. Defaults to `latest`. |
+| `condition` | `string` | No | Scenario in which the command produces the event. |
+
+The `version` on the received command also defaults to `latest` when omitted.
+
+## Explore command and event relationships
+
+The command page lists its events under **Triggers**. Each event page lists the commands that can produce it under **Triggered by**. Message maps also show the command, the resource handling it, and the resulting events.
+
+The example below shows the `Cancel Order` command mapped to the `Order Cancelled` event through the `Order Service`, including the scenario in which the event is produced.
+
+![Cancel Order command mapped to the Order Cancelled event through the Order Service](./imgs/cancel-order-command-to-event.png)
+
+Select **Map commands to events** under **Architecture** to compare these relationships. EventCatalog draws each command-to-event path through the receiving service or domain and groups repeated paths into selectable scenarios.
+
+The **Map commands to events** link is only generated for messages that participate in at least one resolved relationship.

package/dist/docs/development/guides/resources/messages/04-message-channels/05-reference.md

@@ -175,3 +175,7 @@ Supported values are `at-most-once`, `at-least-once`, and `exactly-once`.
 deliveryGuarantee: at-least-once
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/messages/10-reference.md

@@ -437,3 +437,7 @@ schemas:
     format: jsonschema
 ---
 ```
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/resources/services/08-reference.md

@@ -8,6 +8,8 @@ title: Services reference
 description: Frontmatter fields, paths, and routes for services in EventCatalog.
 ---
 
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
 This page lists the fields, paths, and routes supported by services.
 
 ## Paths
@@ -132,6 +134,12 @@ receives:
 ---
 ```
 
+#### Map commands to events
+
+<AddedIn version="4.2.0" />
+
+Each received command can declare the events it triggers. See [Map commands to events](/docs/development/guides/resources/messages/connect-messages/map-commands-to-events) for the supported fields, scenarios, and generated views.
+
 ### `entities` {#entities}
 
 - Type: `array`
@@ -293,3 +301,7 @@ flows:
 ```
 
 If `version` is omitted, EventCatalog uses the latest version.
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/docs/development/guides/systems/06-reference.md

@@ -327,3 +327,7 @@ actors:
 | `name` | `string` | Display name shown in diagrams. Optional. |
 | `label` | `string` | Text shown on the actor relationship edge. Optional. |
 | `direction` | `inbound` or `outbound` | `inbound` means actor to system. `outbound` means system to actor. Defaults to `inbound`. |
+
+## Custom properties
+
+You can add organization-specific metadata to this resource using frontmatter fields prefixed with `x-`. Learn how to define, render, and reference them in [Custom properties on resources](/docs/development/customization/custom-properties).

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -1,6 +1,6 @@
 import {
   log_build_default
-} from "./chunk-QQC5UX3E.js";
+} from "./chunk-GCEFDCZB.js";
 import "./chunk-K2XIENVT.js";
 import {
   runMigrations
@@ -14,10 +14,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-I4TTHHXI.js";
+} from "./chunk-WVIOZDVK.js";
 import {
   logger
-} from "./chunk-M2YEUPPP.js";
+} from "./chunk-5MIGBCON.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -27,7 +27,7 @@ import {
 import {
   watch
 } from "./chunk-CAJUIMDJ.js";
-import "./chunk-WOASLQ3F.js";
+import "./chunk-BXEGST4Z.js";
 import {
   createAstroDevLineFilter,
   createAstroLineFilter
@@ -38,7 +38,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-DGDCWOWP.js";
+} from "./chunk-J2MVHSKA.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-I4TTHHXI.js";
-import "./chunk-M2YEUPPP.js";
-import "./chunk-DGDCWOWP.js";
+} from "./chunk-WVIOZDVK.js";
+import "./chunk-5MIGBCON.js";
+import "./chunk-J2MVHSKA.js";
 import "./chunk-6QENHZZP.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.2.3";
+var version = "4.2.4";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-M2YEUPPP.js";
-import "../chunk-DGDCWOWP.js";
+} from "../chunk-5MIGBCON.js";
+import "../chunk-J2MVHSKA.js";
 export {
   logger
 };

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.2.3",
+  "version": "4.2.4",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
   ],
   "dependencies": {
     "@ai-sdk/react": "^3.0.17",
-    "@astrojs/markdown-remark": "^7.2.0",
-    "@astrojs/mdx": "^7.0.0",
-    "@astrojs/node": "^11.0.0",
-    "@astrojs/react": "^6.0.0",
-    "@astrojs/rss": "^4.0.18",
+    "@astrojs/markdown-remark": "^7.2.1",
+    "@astrojs/mdx": "^7.0.3",
+    "@astrojs/node": "^11.0.2",
+    "@astrojs/react": "^6.0.1",
+    "@astrojs/rss": "^4.0.19",
     "@asyncapi/avro-schema-parser": "3.0.24",
     "@asyncapi/parser": "^3.6.0",
     "@asyncapi/react-component": "3.1.0",
@@ -61,7 +61,7 @@
     "@tanstack/react-table": "^8.17.3",
     "@xyflow/react": "^12.3.6",
     "ai": "^6.0.17",
-    "astro": "^7.0.3",
+    "astro": "^7.1.1",
     "astro-compress": "^2.4.0",
     "astro-expressive-code": "^0.44.0",
     "astro-seo": "^0.8.4",
@@ -76,9 +76,9 @@
     "elkjs": "^0.10.0",
     "glob": "^13.0.6",
     "gray-matter": "^4.0.3",
-    "hono": "4.12.25",
+    "hono": "4.12.27",
     "html-to-image": "^1.11.11",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.0",
     "jsonpath-plus": "^10.4.0",
     "jsonwebtoken": "^9.0.2",
     "lodash.debounce": "^4.0.8",
@@ -117,8 +117,8 @@
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
     "@eventcatalog/sdk": "2.26.1",
-    "@eventcatalog/visualiser": "^4.1.0",
-    "@eventcatalog/linter": "1.1.6"
+    "@eventcatalog/linter": "1.1.6",
+    "@eventcatalog/visualiser": "^4.1.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",