@eventcatalog/core 4.1.2 → 4.1.4

package/dist/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md

@@ -0,0 +1,138 @@
+---
+sidebar_position: 4
+keywords:
+  - EventCatalog custom pages reference
+  - EventCatalog pages prefix
+  - custom routes reference
+sidebar_label: Reference
+title: Custom pages and API routes reference
+description: Route, file, and configuration reference for custom pages and API routes.
+---
+
+## Route prefix
+
+Custom pages and API routes are served under `/custom` by default.
+
+Use `pages.prefix` to serve them somewhere else.
+
+```js title="eventcatalog.config.js"
+export default {
+  pages: {
+    prefix: 'internal/tools',
+  },
+};
+```
+
+With this configuration:
+
+| File | Route |
+| --- | --- |
+| `pages/reports.astro` | `/internal/tools/reports` |
+| `pages/api/services.ts` | `/internal/tools/api/services` |
+
+The prefix must use URL-safe characters: letters, numbers, `-`, and `_`, optionally separated with `/`.
+
+The prefix cannot be empty.
+
+Some top-level routes are reserved by EventCatalog. If a configured prefix conflicts with a reserved route, EventCatalog will ask you to choose a different prefix.
+
+## Routable files
+
+Code files in the top-level `pages` directory are treated as custom routes.
+
+| Extension | Route type |
+| --- | --- |
+| `.astro` | Page |
+| `.ts` | Endpoint |
+| `.js` | Endpoint |
+| `.mjs` | Endpoint |
+
+Other files in `pages`, such as images, are copied as static assets. For example, `pages/diagram.png` can be referenced from `/generated/pages/diagram.png`.
+
+## Route patterns
+
+| File | Default route |
+| --- | --- |
+| `pages/reports.astro` | `/custom/reports` |
+| `pages/reports/index.astro` | `/custom/reports` |
+| `pages/reports/[id].astro` | `/custom/reports/[id]` |
+| `pages/docs/[...slug].astro` | `/custom/docs/[...slug]` |
+| `pages/api/teams.ts` | `/custom/api/teams` |
+| `pages/data.json.ts` | `/custom/data.json` |
+
+## Ignored files and folders
+
+Files or folders that start with `_` are not treated as routes.
+
+Use this for partials, helpers, and colocated components.
+
+| File | Result |
+| --- | --- |
+| `pages/_partial.astro` | Ignored |
+| `pages/_components/Card.astro` | Ignored |
+| `pages/reports/_helpers.ts` | Ignored |
+| `pages/reports/index.astro` | `/custom/reports` |
+
+## Homepage exception
+
+`pages/homepage.astro` is rendered as the catalog homepage at `/`.
+
+It is not served as `/custom/homepage`.
+
+## Server mode
+
+Custom pages can be used in static or server output.
+
+Custom API routes require server mode for production builds.
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+If EventCatalog finds API routes in `pages/api` during a static build, the build fails and asks you to enable server mode or remove the `pages/api` directory.
+
+## Import aliases
+
+Use these aliases in custom pages.
+
+| Alias | Description |
+| --- | --- |
+| `@catalog/layouts/Layout.astro` | Stable EventCatalog layout shell for custom pages. |
+| `@catalog/utils` | Stable catalog data helpers such as `getServices`, `getDomains`, and `getEvents`. |
+| `@catalog/components/*` | Components from your catalog's top-level `components` directory. |
+
+## `@catalog/utils`
+
+Use `@catalog/utils` to read catalog resources from custom pages and API routes.
+
+```js title="pages/reports.astro"
+---
+import { getServices, getDomains } from '@catalog/utils';
+
+const services = await getServices({ getAllVersions: false });
+const domains = await getDomains({ getAllVersions: false });
+---
+```
+
+Getter functions return hydrated, cached collection entries. Pass `{ getAllVersions: false }` when you only want the latest version of each resource.
+
+| Helper | Returns |
+| --- | --- |
+| `getDomains` | Domains |
+| `getServices` | Services |
+| `getSystems` | Systems |
+| `getEvents` | Events |
+| `getCommands` | Commands |
+| `getQueries` | Queries |
+| `getFlows` | Flows |
+| `getChannels` | Channels |
+| `getEntities` | Entities |
+| `getAgents` | Agents |
+| `getContainers` | Containers |
+| `getDataProducts` | Data products |
+| `getAdrs` | Architecture decision records |
+| `getTeams` | Teams |
+| `getUsers` | Users |
+| `getItemsFromCollectionByIdAndSemverOrLatest` | A specific version, semver range, or latest item from a collection |

package/dist/docs/development/customization/05-custom-pages-and-api-routes/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Custom pages and API routes",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/customization/custom-pages-and-api-routes",
+    "title": "Custom pages and API routes",
+    "description": "Add custom pages, internal tools, dashboards, and API routes to your EventCatalog."
+  }
+}

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

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 1
+sidebar_position: 5
 keywords:
 - EventCatalog tables
-sidebar_label: Customize tables
+sidebar_label: Tables
 title: Customize tables
 description: Customize tables in EventCatalog
 ---
@@ -191,4 +191,4 @@ teams: {
 
 
 
-You can read the `eventcatalog.config.js` API reference for [more information on the table configuration](/docs/api/config#domains).
+You can read the `eventcatalog.config.js` API reference for [more information on the table configuration](/docs/api/config#domains).

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

@@ -0,0 +1,190 @@
+---
+sidebar_position: 7
+keywords:
+- EventCatalog resource icons
+- custom icons
+- resource customization
+sidebar_label: Resource icons
+title: Resource icons
+description: Customize the icons shown for resources in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="3.28.1" />
+
+Resource icons let you replace the default icon EventCatalog uses for a resource.
+
+Use them when you want services, messages, data stores, agents, or other catalog resources to show the technology, platform, vendor, or domain-specific concept they represent.
+
+Resource icons can appear in places like:
+
+- Resource page headers
+- Search and discover results
+- Resource references
+- Sidebar navigation
+- Visualizer nodes
+
+## Set a resource icon
+
+Add `styles.icon` to the resource frontmatter.
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+summary: Handles order placement and order history.
+styles:
+  icon: /icons/languages/nodejs.svg
+---
+```
+
+The icon value must be either:
+
+- a path to a file in your catalog's `public` folder
+- an absolute `https://` or `http://` URL
+
+## Use icons from your catalog
+
+Put icon files in your catalog's `public` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'icons',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'languages',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: 'nodejs.svg', highlight: true },
+                { name: 'go.svg', highlight: true },
+              ],
+            },
+            {
+              name: 'database',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'postgresql.svg', highlight: true }],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Files in `public` are served from the root of your catalog, so `public/icons/languages/nodejs.svg` is referenced as `/icons/languages/nodejs.svg`.
+
+## Use external icon URLs
+
+You can also use an absolute URL.
+
+```md title="/services/StripePayments/index.mdx"
+---
+id: StripePayments
+name: Stripe Payments
+version: 1.0.0
+summary: External payment provider used for card payments.
+externalSystem: true
+styles:
+  icon: https://cdn.simpleicons.org/stripe
+---
+```
+
+[Simple Icons CDN](https://cdn.simpleicons.org) is useful for common technology and vendor logos.
+
+## Examples
+
+### Service icon
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+styles:
+  icon: /icons/languages/java.svg
+---
+```
+
+### Data store icon
+
+```md title="/containers/orders-db/index.mdx"
+---
+id: orders-db
+name: Orders DB
+version: 1.0.0
+container_type: database
+technology: postgres@16
+styles:
+  icon: /icons/database/postgresql.svg
+---
+```
+
+### Message icon
+
+```md title="/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 1.0.0
+summary: Raised when an order is placed.
+styles:
+  icon: /icons/events/eventbridge.svg
+---
+```
+
+## Supported file types
+
+Use image files that browsers can render, such as:
+
+- SVG
+- PNG
+- WEBP
+
+SVG icons usually work best because they stay sharp at different sizes.
+
+## Resource icons vs sidebar icons
+
+Resource icons use file paths or URLs through `styles.icon`.
+
+```md
+styles:
+  icon: /icons/languages/nodejs.svg
+```
+
+Application and documentation sidebar icons are different. Those use icon names from [Lucide](https://lucide.dev/icons/) in your sidebar configuration.
+
+```js title="eventcatalog.config.js"
+export default {
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'docs', icon: 'BookOpen' }],
+      },
+    ],
+  },
+};
+```
+
+Use `styles.icon` when you want to customize a resource. Use sidebar icon names when you want to customize navigation.
+
+## Tips
+
+- Keep icons simple and readable at small sizes.
+- Prefer square or near-square assets.
+- Store shared icons under `public/icons`.
+- Use consistent folder names, such as `/icons/languages`, `/icons/database`, or `/icons/tools`.
+- Use external URLs only when you are comfortable depending on that external service at runtime.

package/dist/docs/development/customization/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Customization",
-  "position": 7,
+  "position": 8,
   "collapsible": false,
   "collapsed": false,
   "link": {

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

@@ -1,6 +1,6 @@
 {
   "label": "Customize Visualizer",
-  "position": 4,
+  "position": 8,
   "collapsible": true,
   "collapsed": true,
   "link": {
@@ -8,4 +8,4 @@
     "slug": "/customize-visualizer",
     "description": "A collection of guides to help you customize the visualizer in your catalog."
   }
-}
+}

package/dist/docs/development/deployment/hosting-options.md

@@ -25,7 +25,6 @@ Here are some guides and places you can host static content
 - [Host with Docker](#hosting-with-docker)
 - [Deploy to NextJS](https://nextjs.org/docs/deployment)
 - [Host in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
-- [Deploying EventCatalog using Helm chart](https://github.com/osodevops/helm-charts/tree/main/charts/eventcatalog)
 
 **Community posts**
 - [Using AWS CDK to Deploy EventCatalog](https://matt.martz.codes/using-aws-cdk-to-deploy-eventcatalog)
@@ -109,4 +108,4 @@ Some features of EventCatalog require a server to run (e.g. [EventCatalog Chat](
 
 If you have a large catalog, you may want to use [SSR mode](/docs/development/deployment/build-ssr-mode) to reduce build times.
 
-:::
+:::

package/dist/docs/development/developer-tools/api-catalog.md

@@ -111,4 +111,4 @@ When the EventCatalog MCP server is enabled, an additional entry pointing at `/d
 
 Only services and domains are included in v1 of this endpoint. Events, commands, queries, data products, schemas, diagrams, teams, and users are out of scope for this release.
 
-For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/developer-tools/llms.txt) and [schemas.txt](/docs/development/developer-tools/schemas.txt).
+For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/ask-your-architecture/llms.txt) and [schemas.txt](/docs/development/ask-your-architecture/schemas.txt).

package/dist/docs/development/developer-tools/eventcatalog-linter.md

@@ -51,9 +51,18 @@ The linter validates all EventCatalog resource types:
 - 📡 **Channels**
 - 🔄 **Flows**
 - 📊 **Entities**
+- 🤖 **Agents**
+- 🧱 **Containers** (including the legacy data store alias)
+- 📈 **Data Products**
+- 🧭 **Diagrams**
+- 📝 **ADRs**
 - 👤 **Users**
 - 👥 **Teams**
 
+<AddedIn version="1.2.0" />
+
+Agents, Containers, Data Products, Diagrams, and ADRs are validated as of version 1.2.0.
+
 ## Quick Start
 
 Get started with the EventCatalog Linter in three simple steps:
@@ -314,7 +323,7 @@ npx @eventcatalog/linter --fail-on-warning
 
 ### Default Behavior
 
-If no `.eventcatalogrc.js` file is found, the linter uses default rules where all validations are set to `'error'`. This ensures strict validation out of the box, making it easy to get started with quality documentation practices.
+If no `.eventcatalogrc.js` file is found, the linter uses the default rules listed above. Most validations are errors by default, while documentation quality checks such as orphan messages, missing descriptions, missing schemas, and deprecated references default to warnings.
 
 ### Package.json Integration
 
@@ -341,17 +350,30 @@ Add to your `package.json` scripts:
 - ✅ Email addresses are valid format
 - ✅ Enum values are from allowed lists
 - ✅ Nested object structures are correct
+- ✅ Common resource configuration is supported, including `attachments`, `editUrl`, `diagrams`, `detailsPanel`, sidebar colors, and GraphQL specifications
 
 ### Reference Validation
 
 - ✅ Services referenced in domains exist
+- ✅ Agents, data products, flows, entities, and subdomains referenced in domains exist
 - ✅ Events/Commands/Queries referenced in services exist
+- ✅ Events/Commands/Queries referenced in agents exist
+- ✅ Data product inputs and outputs reference existing resources
+- ✅ ADR relationships and typed `appliesTo` references exist
 - ✅ Entities referenced in domains/services exist
+- ✅ Channels referenced in sends/receives `to`/`from`, routes, messages, and message channels exist
+- ✅ Containers referenced in `writesTo`/`readsFrom` exist
+- ✅ Diagrams referenced from other resources exist
 - ✅ Users/Teams referenced as owners exist
-- ✅ Flow steps reference existing services/messages
+- ✅ User/team owned resources and team members exist
+- ✅ Flow steps reference existing services/messages/agents/containers/data products
 - ✅ Entity properties reference existing entities
 - ✅ Version-specific references are valid
 
+<AddedIn version="1.2.0" />
+
+The expanded reference checks for agents, data products, ADRs, diagrams, and flow steps were added in version 1.2.0.
+
 ## Example Output
 
 ### ✅ Success Output
@@ -475,6 +497,9 @@ The linter provides descriptive rule names in parentheses to help identify and f
 - `(refs/owner-exists)` - Referenced owner (user/team) doesn't exist
 - `(refs/valid-version-range)` - Referenced version doesn't exist or invalid pattern
 - `(refs/resource-exists)` - Referenced resource doesn't exist
+- `(refs/channel-exists)` - Referenced channel in sends/receives `to`/`from`, routes, messages, or message channels doesn't exist
+- `(refs/container-exists)` - Referenced container in `writesTo`/`readsFrom` or flow steps doesn't exist
+- `(refs/orphan-messages)` - Event/command/query has no producer and no consumer
 
 ### Best Practice Rules
 
@@ -547,6 +572,116 @@ deprecated: false
 ---
 ```
 
+#### Agent
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-agent
+name: Refund Agent
+version: 1.0.0
+summary: Coordinates customer refund decisions
+owners:
+  - platform-team
+receives:
+  - id: refund-requested
+    from:
+      - id: refunds
+sends:
+  - id: refund-approved
+    to:
+      - id: public-events/orders
+readsFrom:
+  - id: orders-db
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+tools:
+  - name: Payment lookup
+    type: mcp
+---
+```
+
+#### Container
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: orders-db
+name: Orders DB
+version: 1.0.0
+summary: Stores order records
+container_type: database
+technology: PostgreSQL
+classification: internal
+access_mode: readWrite
+authoritative: true
+---
+```
+
+#### Data product
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-analytics
+name: Refund Analytics
+version: 1.0.0
+summary: Curated refund metrics for finance teams
+inputs:
+  - id: refund-approved
+  - id: orders-db
+outputs:
+  - id: public-events/orders
+    contract:
+      path: contracts/refund-analytics.json
+      name: Refund Analytics Contract
+---
+```
+
+#### ADR
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: adr-001
+name: Use event-driven refunds
+version: 1.0.0
+summary: Records the decision to coordinate refunds through events
+status: accepted
+date: 2026-05-26
+decisionMakers:
+  - id: platform-team
+    collection: teams
+appliesTo:
+  - type: service
+    id: order-service
+  - type: data-product
+    id: refund-analytics
+related:
+  - id: adr-000
+---
+```
+
+#### Diagram
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-flow
+name: Refund Flow Diagram
+version: 1.0.0
+summary: Shows the refund workflow across services and agents
+owners:
+  - platform-team
+---
+```
+
 ### Common Validation Errors
 
 #### ❌ Missing Required Fields

package/dist/docs/development/governance/_category_.json

@@ -1,6 +1,7 @@
 {
   "label": "Governance Patterns",
   "position": 9,
+  "className": "hidden",
   "collapsible": true,
   "collapsed": false
 }

package/dist/docs/development/governance/architecture-change-detection/01-introduction.md

@@ -5,9 +5,9 @@ title: Architecture Change Detection
 description: Know when your event-driven architecture changes. Get notified when services start or stop producing and consuming messages.
 ---
 
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-<EventCatalogPro />
+<PlanBanner plan="Scale" />
 
 Services get added. Consumers change. Producers disappear. In event-driven systems, these relationship changes often go unnoticed until something breaks downstream.