@eventcatalog/core 4.1.3 → 4.1.4

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

@@ -0,0 +1,247 @@
+---
+keywords:
+- EventCatalog ADRs
+- Architecture decision records
+- ADR frontmatter
+sidebar_label: Reference
+title: Architecture decision records reference
+description: Frontmatter fields, paths, and routes for architecture decision records in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by architecture decision records.
+
+## Paths
+
+ADRs can be created in any `adrs` folder:
+
+```txt
+/adrs/{ADR Name}/index.mdx
+/domains/{Domain Name}/adrs/{ADR Name}/index.mdx
+/systems/{System Name}/adrs/{ADR Name}/index.mdx
+```
+
+Versioned ADRs use:
+
+```txt
+/adrs/{ADR Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/adrs/{adr-id}/{version}` | ADR documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the decision record. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: adr-001-use-event-driven-checkout
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the decision record.
+
+```md title="Example"
+---
+name: Use event-driven checkout
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the decision record.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `status` {#status}
+
+- Type: `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded`
+
+Lifecycle status for the decision.
+
+```md title="Example"
+---
+status: accepted
+---
+```
+
+### `date` {#date}
+
+- Type: `date`
+
+Date the decision was created or recorded.
+
+```md title="Example"
+---
+date: 2026-06-01
+---
+```
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary shown in lists and search.
+
+```md title="Example"
+---
+summary: Checkout will publish domain events for downstream fulfilment.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+Teams or users that own the decision record.
+
+```md title="Example"
+---
+owners:
+  - architecture-team
+---
+```
+
+### `decisionMakers` {#decisionMakers}
+
+- Type: `array`
+
+Teams or users that made or approved the decision.
+
+```md title="Example"
+---
+decisionMakers:
+  - architecture-review-board
+---
+```
+
+### `appliesTo` {#appliesTo}
+
+- Type: `array`
+
+Resources affected by this decision.
+
+```md title="Example"
+---
+appliesTo:
+  - type: system
+    id: checkout-system
+---
+```
+
+### `supersedes` {#supersedes}
+
+- Type: `array`
+
+Decision records replaced by this decision.
+
+```md title="Example"
+---
+supersedes:
+  - id: adr-000-old-checkout-design
+---
+```
+
+### `supersededBy` {#supersededBy}
+
+- Type: `array`
+
+Decision records that replace this decision.
+
+```md title="Example"
+---
+supersededBy:
+  - id: adr-004-new-checkout-design
+---
+```
+
+### `amends` {#amends}
+
+- Type: `array`
+
+Decision records amended by this decision.
+
+```md title="Example"
+---
+amends:
+  - id: adr-002-payment-routing
+---
+```
+
+### `amendedBy` {#amendedBy}
+
+- Type: `array`
+
+Decision records that amend this decision.
+
+```md title="Example"
+---
+amendedBy:
+  - id: adr-005-payment-retry-policy
+---
+```
+
+### `related` {#related}
+
+- Type: `array`
+
+Related decision records.
+
+```md title="Example"
+---
+related:
+  - id: adr-003-order-events
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the decision record page.
+
+```md title="Example"
+---
+badges:
+  - content: Accepted
+    backgroundColor: green
+    textColor: green
+---
+```
+
+## Applies to
+
+Use `appliesTo` to link the decision to resources.
+
+```md
+---
+appliesTo:
+  - type: system
+    id: checkout-system
+  - type: service
+    id: payment-service
+  - type: event
+    id: PaymentAuthorized
+---
+```
+
+Supported resource types include `agent`, `service`, `system`, `event`, `command`, `query`, `flow`, `channel`, `domain`, `user`, `team`, `container`, `entity`, `diagram`, and `data-product`.

package/dist/docs/development/guides/resources/adrs/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Architecture Decision Records",
+  "position": 9,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/adrs",
+    "description": "A collection of guides to help you document and manage architecture decision records in EventCatalog."
+  }
+}

package/dist/docs/development/guides/{agents → resources/agents}/01-introduction.md

@@ -12,15 +12,11 @@ description: Document and govern AI agents alongside your services and events.
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="3.41.0" />
-
 In EventCatalog, agents represent AI-powered components in your architecture. They sit alongside services, messages, domains, and flows as first-class catalog resources.
 
 An agent typically wraps a large language model (LLM) and is given access to tools (MCP servers, APIs, databases) so it can take autonomous or semi-autonomous actions.
 
-![Agent detail page showing model, tools, and connected messages](./img/agent-documentation.png)
-
-## Why document agents?
+### Why document agents?
 
 As AI agents take on real responsibilities in production systems they become part of your architecture whether or not they are documented.
 
@@ -30,14 +26,3 @@ Cataloging them gives your team:
 - **Model governance** — the `model` block captures which provider, model, and snapshot version the agent runs on so drift is visible in the catalog.
 - **Tool transparency** — the `tools` array lists every external capability (MCP server, API, database) the agent can reach.
 
-## Where agents live in your architecture
-
-Agents can belong to a domain or subdomain, or sit at the root of your catalog alongside services. They participate in flows as first-class steps and appear in search, the sidebar, and the discover page.
-
-![Agent rendered as a node in the EventCatalog visualiser, connected to its tools and messages](./img/agent-visualizer.png)
-
-## Finding agents in your catalog
-
-Agents appear in the discover page alongside services, messages, domains, and flows. You can search, filter, and browse them the same way you would any other resource.
-
-![Explore page listing agents in the catalog with their owners and domains](./img/explore-agents.png)

package/dist/docs/development/guides/resources/agents/02-create-agent.md

@@ -0,0 +1,188 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog agents
+- AI agents
+- creating agents
+sidebar_label: Create an agent
+title: Create an agent
+description: Creating and managing agents within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Agents document AI-powered capabilities in your architecture. Use them for assistants, autonomous workers, copilots, review agents, or any LLM-backed component that can reason over data, call tools, receive messages, or send messages.
+
+You can also add [model metadata](/docs/development/guides/resources/agents/model-metadata), [tools](/docs/development/guides/resources/agents/adding-tools), [messages](/docs/development/guides/resources/agents/add-messages-to-agents), and [data stores](/docs/development/guides/resources/agents/add-data-stores-to-agents) to your agents.
+
+![Example](./img/agent-documentation.png)
+
+## Adding a new agent
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog agent">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/agents/create-agent.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/agents.md then help me create a new EventCatalog agent in my catalog.
+
+Ask me for the agent name, what the agent does, summary, model provider/name/version if known, tools it can call, messages it receives or sends, data stores it reads from or writes to, and whether it belongs at the root of the catalog or inside a domain. Then create the correct agents/{'{Agent Name}'}/index.mdx or domains/{'{Domain Name}'}/agents/{'{Agent Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any domains, put it into the root agents folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the agent should live, create the right folder structure, and add the first version of the agent documentation.
+
+### Manual Creation
+
+Agents can live at the root of your catalog or inside a domain.
+
+Create a new folder for the agent with an `index.mdx` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'agents',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'FraudReviewAgent',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the agent belongs to a domain, keep it inside that domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Payments',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'agents',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'FraudReviewAgent',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+You can also place agents inside a subdomain when the agent belongs to a more specific business boundary.
+
+## Create the agent file
+
+Create an `index.mdx` file for the agent.
+
+_Here is an example of what an agent markdown file may look like._
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+# id of your agent, used for slugs and references in EventCatalog.
+id: FraudReviewAgent
+
+# Display name of the Agent, rendered in EventCatalog
+name: Fraud Review Agent
+
+# Version of the Agent
+version: 0.0.1
+
+# Short summary of your Agent
+summary: |
+  Reviews risky payments, explains fraud signals, and recommends whether payment processing should continue.
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  provider: OpenAI
+  name: gpt-4.1
+  version: "2025-04-14"
+
+# Optional external tools the agent can call
+tools:
+  - name: Risk profile lookup
+    type: mcp
+    icon: /icons/tools/datadog.svg
+    url: https://mcp.example.com/fraud/risk-profile
+    description: Retrieves transaction anomaly, device fingerprint, and fraud model signals.
+
+# Optional messages this agent receives and its version
+receives:
+  - id: PaymentInitiated
+    version: 0.0.1
+
+# Optional messages this agent sends and its version
+sends:
+  - id: FraudReviewCompleted
+    version: 0.0.1
+
+# Optional data stores this agent reads from
+readsFrom:
+  - id: fraud-analytics-db
+    version: 0.0.1
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: AI Agent
+      backgroundColor: purple
+      textColor: purple
+---
+
+## Overview
+
+The Fraud Review Agent reviews risky payment attempts before they continue through the payment gateway.
+
+<NodeGraph />
+
+## Tools
+
+<AgentTools />
+```
+
+## Attaching an agent to a domain
+
+To associate an agent with a domain, add its `id` to the `agents` array in the domain's frontmatter:
+
+```md title="/domains/Payment/index.mdx (example)"
+---
+id: Payment
+name: Payment Domain
+version: 0.0.1
+agents:
+  - id: FraudReviewAgent
+    version: 0.0.1
+services:
+  - id: PaymentService
+    version: 0.0.1
+---
+```
+
+EventCatalog will show the agent in the domain sidebar and include it in the domain visualiser.

package/dist/docs/development/guides/{agents → resources/agents}/03-adding-tools.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 keywords:
 - EventCatalog agents
 - agent tools
 - MCP
 - AgentTools component
-sidebar_label: Agent tools
-title: Agent tools
+sidebar_label: Add tools to agents
+title: Add tools to agents
 description: Document and display the tools an agent can call.
 ---
 
@@ -89,4 +89,3 @@ This agent helps the support team answer order questions.
 `<AgentTools />` is only supported inside agent pages. If you add it to a service or message page, the catalog will display a warning and skip the table.
 
 ![Agent tools table with MCP badge and icon columns](./img/agent-tools-component.png)
-

package/dist/docs/development/guides/{agents → resources/agents}/04-model-metadata.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 keywords:
 - EventCatalog agents
 - LLM model
@@ -93,4 +93,4 @@ All three fields are optional strings. Use whatever convention your provider use
 
 ## Model changes and versioning
 
-When you upgrade the model an agent uses, consider whether the behavior change is significant enough to warrant a new agent version. Capturing the new `model.version` in a versioned snapshot (see [Versioning](/docs/development/guides/agents/versioning-and-lifecycle/versioning)) gives your team a clear record of when the model changed and who approved it.
+When you upgrade the model an agent uses, consider whether the behavior change is significant enough to warrant a new agent version. Capturing the new `model.version` in a versioned snapshot (see [Version agents](/docs/development/guides/versioning-resources)) gives your team a clear record of when the model changed and who approved it.

package/dist/docs/development/guides/{agents/adding-to-agents/01-messages.md → resources/agents/05-add-messages-to-agents.md}

@@ -3,7 +3,8 @@ keywords:
 - EventCatalog agents
 - agent messages
 - sends receives
-sidebar_label: Messages
+sidebar_position: 5
+sidebar_label: Add messages to agents
 title: Adding messages to agents
 description: Connecting agents to the messages they produce and consume.
 ---
@@ -16,7 +17,7 @@ An agent can **receive** messages (events, commands, or queries) that trigger it
 
 Connecting agents to messages keeps the full event topology visible in the visualiser and lets your team trace which agents react to which events.
 
-![Agent visualiser showing received events, connected services, and data stores](../img/agent-consuming-messages.png)
+![Agent visualiser showing received events, connected services, and data stores](./img/agent-consuming-messages.png)
 
 ## Adding messages to your agent
 
@@ -81,7 +82,7 @@ receives:
 ---
 ```
 
-You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/channels/introduction).
+You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/resources/messages/message-channels/introduction).
 
 ### Using semver versioning
 
@@ -119,4 +120,4 @@ Although it's recommended to link to a version of a message it is now optional.
 
 When messages get added within your agents EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.
 
-![Agent node graph showing sends and receives connections](../img/agent-visualizer.png)
+![Agent node graph showing sends and receives connections](./img/agent-visualizer.png)

package/dist/docs/development/guides/{agents/adding-to-agents/02-datastores.md → resources/agents/06-add-data-stores-to-agents.md}

@@ -3,7 +3,8 @@ keywords:
 - EventCatalog agents
 - agent data stores
 - writesTo readsFrom
-sidebar_label: Data stores
+sidebar_position: 6
+sidebar_label: Add data stores to agents
 title: Adding data stores to agents
 description: Document the data stores an agent reads from or writes to.
 ---
@@ -12,7 +13,7 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 <AddedIn version="3.41.0" />
 
-[Data stores](/docs/development/guides/data/introduction) are containers that hold data in your architecture — databases, caches, object stores, search indexes, and so on. Agents can read from and write to these containers, and documenting those relationships keeps the full data-access picture visible in the visualiser.
+[Data stores](/docs/development/guides/resources/data/introduction) are containers that hold data in your architecture — databases, caches, object stores, search indexes, and so on. Agents can read from and write to these containers, and documenting those relationships keeps the full data-access picture visible in the visualiser.
 
 ## Specify read/write relationships
 
@@ -47,16 +48,4 @@ If no version is provided, EventCatalog uses the latest version of the data stor
 
 When data stores are connected to an agent, EventCatalog visualizes the read/write relationships — either via the `<NodeGraph />` component on the agent page or through the full-screen visualiser.
 
-![Agent visualiser showing data store nodes connected with reads and writes](../img/agent-consuming-messages.png)
-
-You can also control the **Containers** section in the agent's sidebar using `detailsPanel`:
-
-```md title="/agents/FraudReviewAgent/index.mdx (example)"
----
-id: FraudReviewAgent
-version: 0.0.1
-detailsPanel:
-  containers:
-    visible: false
----
-```
+![Agent visualiser showing data store nodes connected with reads and writes](./img/agent-consuming-messages.png)