@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/01-getting-started/project-structure.md

@@ -0,0 +1,269 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog project structure
+sidebar_label: Project structure
+title: Project structure
+description: Understanding how to structure your EventCatalog project
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+An EventCatalog project is a folder of Markdown files that describe and model your architecture.
+
+Each resource in your catalog, such as a domain, service, event, command, query, team, or diagram, is represented by a file or folder in your project. EventCatalog reads those files and turns them into a catalog.
+
+You can also bring your own documentation into EventCatalog, such as architecture decision records, guides, onboarding material, or runbooks. Learn more about [bringing your own documentation](/docs/development/bring-your-own-documentation/introduction).
+
+All resource types are optional. You decide what you want to document, and you can add more resource types later as your catalog becomes more useful to your teams.
+
+## Directories and files
+
+Every EventCatalog project has a few core files used to run and configure the catalog. The resource folders, such as `domains/`, `services/`, `channels/`, and `diagrams/`, are optional and depend on what you want to document.
+
+EventCatalog creates resources from folders that contain an `index.mdx` file. For example, `domains/Orders/index.mdx` creates an `Orders` domain, and `domains/Orders/services/OrderService/index.mdx` creates an `OrderService` service inside that domain.
+
+- `eventcatalog.config.js` - Configures your catalog.
+- `package.json` - Defines scripts and dependencies.
+- `public/` - Stores static assets that should be served directly.
+- `domains/` - Documents business domains and bounded contexts.
+- `services/` - Documents services, APIs, applications, external systems, jobs, and workers.
+- `events/`, `commands/`, `queries/` - Documents messages.
+- `channels/` - Documents topics, queues, streams, webhooks, or other communication paths.
+- `diagrams/` - Documents architecture diagrams and flows.
+- `teams/` and `users/` - Documents ownership metadata.
+
+### Example project tree
+
+A common EventCatalog project directory might look like this:
+
+<ProjectTree
+  items={[
+    { name: 'eventcatalog.config.js' },
+    { name: 'package.json' },
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'services',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderService',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'index.mdx' },
+                    { name: 'openapi.yaml' },
+                    { name: 'asyncapi.yaml' },
+                    {
+                      name: 'events',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'OrderPlaced',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [
+                            { name: 'index.mdx' },
+                            { name: 'schema.avsc' },
+                          ],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'commands',
+                      type: 'folder',
+                      defaultOpen: false,
+                      children: [
+                        {
+                          name: 'CancelOrder',
+                          type: 'folder',
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'queries',
+                      type: 'folder',
+                      defaultOpen: false,
+                      children: [
+                        {
+                          name: 'GetOrder',
+                          type: 'folder',
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'channels',
+      type: 'folder',
+      defaultOpen: false,
+      children: [
+        {
+          name: 'orders.events',
+          type: 'folder',
+          children: [{ name: 'index.mdx' }],
+        },
+      ],
+    },
+    {
+      name: 'diagrams',
+      type: 'folder',
+      defaultOpen: false,
+      children: [
+        {
+          name: 'system-context',
+          type: 'folder',
+          children: [{ name: 'index.mdx' }],
+        },
+      ],
+    },
+    {
+      name: 'teams',
+      type: 'folder',
+      defaultOpen: false,
+      children: [{ name: 'mobile-team.mdx' }],
+    },
+    {
+      name: 'users',
+      type: 'folder',
+      defaultOpen: false,
+      children: [{ name: 'dboyne.mdx' }],
+    },
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: false,
+      children: [
+        {
+          name: 'icons',
+          type: 'folder',
+          children: [{ name: 'orders.svg' }],
+        },
+      ],
+    },
+  ]}
+/>
+
+You do not need every folder on day one. Start with the resources you know about, then add more as your catalog grows.
+
+### `domains/`
+
+The `domains/` folder documents the business areas or bounded contexts in your architecture, such as `Orders`, `Payments`, or `Shipping`.
+
+Domains can contain their own documentation, services, messages, diagrams, and other resources. This is the most common way to structure larger catalogs because related architecture stays close together.
+
+Learn more in the [domains guide](/docs/development/guides/domains/introduction).
+
+### `services/`
+
+The `services/` folder documents services, APIs, applications, external systems, jobs, and workers.
+
+Services can live inside a domain, such as `domains/Orders/services/OrderService/`, or at the root of your catalog, such as `services/OrderService/`.
+
+Services often contain OpenAPI, AsyncAPI, or GraphQL specifications and the messages they own.
+
+Learn more in the [services guide](/docs/development/guides/services/introduction).
+
+### `events/`, `commands/`, and `queries/`
+
+The `events/`, `commands/`, and `queries/` folders document messages exchanged between services.
+
+These folders can live inside a service when that service owns the message, or elsewhere in your catalog if you prefer a flatter structure.
+
+Message folders can also contain schemas, examples, and version history.
+
+Learn more in the [messages guide](/docs/development/guides/messages/overview).
+
+### `channels/`
+
+The `channels/` folder documents where messages flow, such as Kafka topics, queues, streams, webhooks, or other integration points.
+
+Use channels when you want to explain the transport layer of your architecture, not just the messages themselves.
+
+Learn more in the [channels guide](/docs/development/guides/channels/introduction).
+
+### `diagrams/`
+
+The `diagrams/` folder documents architecture diagrams, flows, and visual explanations.
+
+Diagrams can live at the root of your catalog or inside another resource, such as a domain or service.
+
+Learn more in the [diagrams guide](/docs/development/guides/diagrams/introduction).
+
+### `teams/` and `users/`
+
+The `teams/` and `users/` folders document ownership metadata.
+
+Teams and users are usually represented as files directly inside their folder:
+
+```bash
+teams/
+└── mobile-team.mdx
+
+users/
+└── dboyne.mdx
+```
+
+Use these when you want ownership to be visible across domains, services, messages, schemas, and other resources.
+
+Learn more in the [teams guide](/docs/development/guides/owners/teams/introduction) and [users guide](/docs/development/guides/owners/users/introduction).
+
+### `public/`
+
+The `public/` folder stores static assets that should be served directly, such as icons, images, and files.
+
+For example, if a service icon lives at `public/icons/orders.svg`, you can reference it from your resource metadata using `/icons/orders.svg`.
+
+### `eventcatalog.config.js`
+
+The `eventcatalog.config.js` file configures your catalog, including title, output mode, integrations, and feature settings.
+
+See the [configuration API](/docs/api/config).
+
+### `package.json`
+
+The `package.json` file defines the scripts and dependencies used to run, build, and preview your catalog.
+
+Most EventCatalog projects include scripts such as `npm run dev` and `npm run build`.
+
+## What should I create first?
+
+If you are starting from an empty catalog, create resources in this order:
+
+1. Add a domain for a business area, such as `Orders`.
+2. Add one service inside that domain.
+3. Add one event, command, or query owned by that service.
+4. Add a team that owns the service.
+5. Add channels or diagrams once you want to explain how things connect.
+
+That gives you a useful catalog quickly without needing to model everything up front.
+
+## Learn more
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/services/introduction)
+- [Messages](/docs/development/guides/messages/overview)
+- [Channels](/docs/development/guides/channels/introduction)
+- [Diagrams](/docs/development/guides/diagrams/introduction)
+- [Teams](/docs/development/guides/owners/teams/introduction)
+- [Users](/docs/development/guides/owners/users/introduction)

package/dist/docs/development/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Development",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development",
+    "title": "EventCatalog documentation",
+    "description": "EventCatalog documentation. Learn about the fundamentals of EventCatalog."
+  }
+}

package/dist/docs/development/_getting-started.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog introduction
+sidebar_label: Getting Started
+title: Getting Started
+description: EventCatalog is an open source project to help you bring discoverability to your event-driven architecture.
+hide_title: true
+hide_table_of_contents: true
+hide_breadcrumbs: true
+---
+
+import DocumentationLanding from '@site/src/components/MDX/DocumentationLanding';
+
+<DocumentationLanding />

package/dist/docs/development/agent-resources/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Agent Resources",
+  "position": 14,
+  "collapsible": true,
+  "collapsed": false
+}

package/dist/docs/development/agent-resources/eventcatalog-skills.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+sidebar_label: EventCatalog Skills
+title: EventCatalog Skills
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://github.com/event-catalog/eventcatalog-skills';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://github.com/event-catalog/eventcatalog-skills">EventCatalog Skills</a>

package/dist/docs/development/agent-resources/llms-full.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 3
+sidebar_label: EventCatalog Docs llms-full.txt
+title: EventCatalog Docs llms-full.txt
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://www.eventcatalog.dev/llms-full.txt';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://www.eventcatalog.dev/llms-full.txt">EventCatalog Docs llms-full.txt</a>

package/dist/docs/development/agent-resources/llms.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 2
+sidebar_label: EventCatalog Docs llms.txt
+title: EventCatalog Docs llms.txt
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://www.eventcatalog.dev/llms.txt';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://www.eventcatalog.dev/llms.txt">EventCatalog Docs llms.txt</a>

package/dist/docs/development/ask-your-architecture/01-intro.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Using AI with EventCatalog
+title: AI with EventCatalog
+description: Architecture documentation for humans and AI
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+EventCatalog helps you document your architecture for both teams and your AI tools. Your team gets a visual catalog to explore your system. Your AI tools get structured access to query and reason about your architecture.
+
+You can disable the AI chat feature at any time by setting `chat.enabled: false` in your `eventcatalog.config.js`. This hides the chat UI and stops chat requests even when all other prerequisites (plan, server mode, config file) are met.
+
+## AI integrations
+
+EventCatalog supports five ways to use AI with your catalog:
+
+- [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant)
+  - Bring your own model to EventCatalog itself, and ask questions about your documentation directly in the browser.
+- [EventCatalog MCP Server](/docs/development/ask-your-architecture/mcp-server/introduction)
+  - Connect your MCP clients (e.g Cursor, Windsurf, Claude Desktop) to EventCatalog.
+- [Slack Integration](/docs/development/ask-your-architecture/slack-integration/introduction)
+  - Query your architecture directly from Slack using the EventCatalog Slack Bot.
+- [AI Skills](/docs/development/ask-your-architecture/skills/introduction)
+  - Pre-built skills that teach AI coding agents how to generate correct EventCatalog documentation.
+- [Bundled docs for coding agents](#bundled-docs-for-coding-agents)
+  - Version-matched docs bundled inside `@eventcatalog/core` so agents always reference accurate APIs, not stale training data.
+
+## Bundled docs for coding agents
+
+<AddedIn version="3.35.1" />
+
+AI coding agents (Claude Code, Cursor, Copilot, and others) are trained on a snapshot of the web. EventCatalog's API, frontmatter conventions, and folder structure evolve with each release, so an agent relying on training data alone may generate outdated or incorrect files.
+
+Starting in `3.35.1`, `@eventcatalog/core` bundles the full documentation inside the package itself. After installing EventCatalog, the docs are available at:
+
+```
+node_modules/@eventcatalog/core/dist/docs/
+```
+
+No extra install or network request is needed. The bundled docs mirror the structure of the EventCatalog website (api, cli, development, plugins, and more) and are always version-matched to the package you have installed.
+
+### Use with new projects
+
+Projects scaffolded with `npx create-eventcatalog@latest` automatically receive two files in the project root:
+
+- `AGENTS.md` — read by most coding agents before they act. It tells the agent to find and read the relevant doc in `node_modules/@eventcatalog/core/dist/docs/` before doing any EventCatalog work.
+- `CLAUDE.md` — a single `@AGENTS.md` line that re-exports the rules for Claude Code without duplicating content.
+
+No manual setup is required for new projects.
+
+### Use with existing projects
+
+Add the two files to the root of your EventCatalog project:
+
+**`AGENTS.md`**
+
+```markdown
+<!-- BEGIN:eventcatalog-agent-rules -->
+# EventCatalog: ALWAYS read docs before coding
+
+Before any EventCatalog work, find and read the relevant doc in `node_modules/@eventcatalog/core/dist/docs/`. Your training data may be outdated. The bundled docs are the source of truth.
+
+<!-- END:eventcatalog-agent-rules -->
+```
+
+**`CLAUDE.md`**
+
+```
+@AGENTS.md
+```
+
+The `BEGIN` / `END` markers in `AGENTS.md` let you add your own project-specific instructions outside the managed block. EventCatalog will only update content inside those markers in future releases.
+
+### Understand the docs layout
+
+The bundled docs follow the same structure as the EventCatalog website:
+
+```
+node_modules/@eventcatalog/core/dist/docs/
+├── api/          # Frontmatter reference for all resource types
+├── cli/          # CLI commands
+├── development/  # Getting started, guides, customization
+└── plugins/      # Generator and plugin documentation
+```
+
+Point your agent at a specific subdirectory when you want it to focus. For example, to document a new service, read `dist/docs/api/04-service-api.md` and `dist/docs/development/guides/services/`.

package/dist/docs/development/ask-your-architecture/02-eventcatalog-assistant/01-what-is-eventcatalog-assistant.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Assistant
+sidebar_label: What is EventCatalog Assistant?
+title: What is EventCatalog Assistant?
+description: Learn how EventCatalog Assistant helps users explore documentation using natural language.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog Assistant allows users to ask questions about your documentation using natural language. It is embedded directly into your documentation site, enabling users to quickly find answers, understand your system, and succeed without manually searching through pages.
+
+**You can bring your own model to EventCatalog and your data is owned by you and never shared.**
+
+The assistant integrates with your preferred AI models using the [AI SDK](https://ai-sdk.dev/), giving you full control over which models power the experience.
+
+![EventCatalog Assistant](./images/example.png)

package/dist/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Assistant
+sidebar_label: Configuration    
+title: Configuration
+description: Configure EventCatalog Assistant
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+**EventCatalog Assistant is turned off by default.**
+
+To enable the assistant feature, you need to set the following:
+
+1. Turn on the `chat` feature in your `eventcatalog.config.js` file and add 
+2. Add a `eventcatalog.chat.js` file to your catalog.
+
+### Enabling the feature
+
+To turn on the assistant feature, you need to set the following:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // Enable the chat feature in your catalog
+  chat: {
+    enabled: true,
+  },
+  // AI integrations require you to run eventcatalog as as server
+  output: 'server'
+};
+```
+
+### Installing your model and configuring `eventcatalog.chat.js` file
+
+First you have to install your model of choice ([list of models](https://ai-sdk.dev/docs/foundations/providers-and-models#ai-sdk-providers)) and configure the relevant secrets in your `.env` file.
+
+_Example of installing the OpenAI model:_
+
+```md
+<!-- in the root of your project -->
+npm install @ai-sdk/openai
+```
+
+#### Configuring `eventcatalog.chat.js`
+
+This file will provide the model and any model configuration to EventCatalog.
+
+In the example below we are using the OpenAI model `gpt-4.1-nano` and configuring the model with some additional parameters.
+
+```js title="eventcatalog.chat.js"
+import { openai } from '@ai-sdk/openai';
+
+// Export your model using the default export
+export default async () => {
+    return openai('gpt-4.1-nano');
+}
+
+// Export the configuration for the model (optional)
+export const configuration = {
+    topP: 0.9,
+    topK: 40,
+    frequencyPenalty: 0.0,
+    presencePenalty: 0.0,
+    temperature: 0.7,
+    maxTokens: 10000,
+}
+```
+
+Once you have enabled the feature and configured your model, restart EventCatalog and you can start asking questions about your architecture.