@eventcatalog/core 5.8.0 → 5.9.0

package/dist/docs/development/ask-your-architecture/07-catch-breaking-changes.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 7
+keywords:
+  - Breaking Changes
+  - EventCatalog Agents
+  - schema governance
+  - schema compatibility
+  - GitHub Actions
+sidebar_label: Catch breaking changes
+title: Catch breaking changes
+description: The Breaking Changes workflow comments on pull requests when a schema change would break a consumer documented in your EventCatalog, with the consumers and their owners.
+slug: /development/agents/set-up-breaking-changes
+---
+
+import { BreakingChangesComment } from '@site/src/components/AgentOutputs';
+import { AgentPrompt } from '@site/src/components/AgentPrompt';
+
+The **Breaking Changes** workflow checks the message schemas changed in a pull request. If a change would break consumers documented in your catalog, it comments with what breaks, who is affected, and who owns them, before the change merges. It never edits your catalog.
+
+<AgentPrompt variant="breaking-changes" />
+
+<BreakingChangesComment />
+
+## How it works
+
+1. **Finds changed schemas.** It looks for changed schema files in the pull request.
+2. **Checks each change.** A change is breaking when existing consumers could fail: a removed or renamed field, a changed type, a new required field, a narrowed enum, and similar. Additive changes, such as a new optional field, are not breaking.
+3. **Finds the consumers.** It matches the schema to its message in your catalog, then finds every service, agent or domain that receives it at an affected version.
+4. **Comments on the pull request** with the breaking lines and each consumer with its owners.
+
+If the pull request changes no schemas, or none of the changes are breaking, it doesn't comment. If a breaking change has no consumers in your catalog, the comment says so.
+
+A consumer is affected when it receives the message at its current version, at `latest` or with no version, or at a range that includes the current version, such as `1.x`. Consumers pinned to an older version are listed too, with their version. The reason given for each consumer comes from your catalog, such as "Receives payment-succeeded 1.0.0". The agent doesn't guess how a consumer uses particular fields.
+
+## Before you start
+
+You need:
+
+- An EventCatalog in a GitHub repository (the **catalog repository**), with the catalog at the root of the repository, and the consumers of your messages documented in it.
+- A repository with message schemas (the **source repository**).
+- An API key for an AI model provider.
+
+## Set it up
+
+In your source repository, add two secrets under **Settings → Secrets and variables → Actions**:
+
+- `ANTHROPIC_API_KEY`, or the key for [your model provider](#models).
+- `EVENTCATALOG_TOKEN`, a GitHub token that can read your catalog repository. The workflow never writes to it.
+
+Then add the workflow. It runs while the pull request is open, so the warning arrives before the change merges:
+
+```yaml title=".github/workflows/eventcatalog-breaking-changes.yml"
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  breaking-changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+      - uses: event-catalog/agents@v2
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          agent: breaking-changes
+          catalog-repo: your-org/your-catalog
+          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+Replace `your-org/your-catalog` with your catalog repository. Keep `fetch-depth: 0`: the agent needs it to compare the pull request with its base branch.
+
+To check it works, open a pull request that removes a field from a schema that a service in your catalog consumes.
+
+If you also [sync docs with your code](/docs/development/agents/set-up-code-to-docs), you can run both from one workflow file: add `closed` to the `types`, and give each job an `if`:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+jobs:
+  breaking-changes:
+    if: github.event.action != 'closed'
+    # ... as above
+
+  code-to-docs:
+    if: github.event.action == 'closed' && github.event.pull_request.merged == true
+    # ...
+```
+
+## Configuration
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | Yes | | Set to `breaking-changes` to run this workflow. |
+| `catalog-repo` | Yes | | Your catalog repository, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | The catalog branch to read. |
+| `catalog-token` | No | `github.token` | A token that can read the catalog repository. |
+| `catalog-url` | No | | The URL of your hosted catalog. The comment links consumers and owners to it. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | The model the agent uses. See [models](#models). |
+| `schema-extensions` | No | `.json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql` | The file extensions treated as message schemas. |
+| `ignore-paths` | No | Build and dependency folders | Comma-separated paths or glob patterns to leave out of the review. |
+
+To check message contracts in other files, such as TypeScript types, set `schema-extensions`. Your list replaces the defaults, so include every extension you want checked:
+
+```yaml
+with:
+  schema-extensions: .json,.yaml,.ts
+```
+
+Only add source code extensions for files that contain message contracts: every changed file with a listed extension is checked.
+
+## Models
+
+Use any model from [these providers](https://pi.dev/models). Set `model` to a provider and model name, and pass your provider's key as an environment variable on the step:
+
+| Provider | Model example | Environment variable |
+| --- | --- | --- |
+| Anthropic | `anthropic/claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
+| OpenAI | `openai/gpt-5.1` | `OPENAI_API_KEY` |
+| OpenRouter | `openrouter/anthropic/claude-sonnet-4.6` | `OPENROUTER_API_KEY` |
+
+To use models in your own AWS account, use an `amazon-bedrock/` model, such as `amazon-bedrock/eu.anthropic.claude-sonnet-4-6`, and give the job AWS credentials with [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials).
+
+## Data and privacy
+
+- **It's read-only.** It only comments on pull requests, and never edits your catalog.
+- **Your code goes to one place:** the model provider you configure. The agent runs in your GitHub Actions runner. EventCatalog never receives your code, your catalog or your pull requests.
+
+Each run sends one anonymous usage event: the outcome and the kind of error if it failed, the model, the run's duration, whether the pull request was open or merged, and the repository name. It never contains code, file names, paths, diffs or pull request content. To turn it off, set `POSTHOG_KEY: ''` in the step's `env`.
+
+## Versions
+
+Use `event-catalog/agents@v2` for the latest v2 release, or an exact release such as `event-catalog/agents@v2.1.0`, which never changes. Releases are listed on [GitHub](https://github.com/event-catalog/agents/tags).

package/dist/docs/development/components/custom-components/02-create-your-first-component.md

@@ -5,8 +5,12 @@ title: Create your first component
 description: Create a small reusable component and render it in a catalog page.
 ---
 
+import { AgentPrompt } from '@site/src/components/AgentPrompt';
+
 In this guide, we will create a simple component and add it to a service page.
 
+<AgentPrompt variant="custom-component" />
+
 ## Create the component
 
 Create a new file in your catalog.

package/dist/docs/development/customization/customize-visualizer/00-visualizer-nodes.md

@@ -30,8 +30,8 @@ name: Notification Service
 summary: |
   Service that handles orders
 styles:
-  icon: "BellIcon"
-  node: 
+  icon: /icons/bell.svg
+  node:
     color: purple
     label: "Custom"
 ---
@@ -45,6 +45,8 @@ styles:
 
 | ID | Required | Default | Description |
 | --- | --- | --- | --- |
-| `styles.icon` | No | Depends on resource type | The icon to use for the resource. Icons are from [hero icons](https://heroicons.com/). <br/> You can find a list of icons [here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/). |
-| `styles.node.color` | No | Depends on resource type | The color to use for the node. These are tailwind colors and you can find a list of them [here](https://tailwindcss.com/docs/colors). |
-| `styles.node.label` | No | Depends on resource type | The label to use for the node (side label). |
+| `styles.icon` | No | Depends on resource type | An icon shown next to the resource's name: a path to an image in your catalog's `public` folder (e.g. `/icons/bell.svg`) or an image URL. Domain, flow and entity nodes also take a [Heroicons](https://heroicons.com/) name (e.g. `BellIcon`). |
+| `styles.node.color` | No | Depends on resource type | The color to use for the node: a [Tailwind color](https://tailwindcss.com/docs/colors) name (e.g. `blue`, `emerald`) or a hex color (e.g. `#0ea5e9`). It colors the node's border, badge and handles. |
+| `styles.node.label` | No | Depends on resource type | The label shown in the node's type badge, in place of its type (e.g. `Service`). |
+
+Colors and labels apply to services, events, commands, queries, channels, data stores, data products, agents and flows.

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

@@ -109,4 +109,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/ask-your-architecture/llms.txt) and [schemas.txt](/docs/development/ask-your-architecture/schemas.txt).
+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).

package/dist/docs/development/{ask-your-architecture/02-llms.txt.md → developer-tools/llms.txt.md}

@@ -52,6 +52,8 @@ The recommended URLs for AI tools are at the catalog root:
  - `https://<your-catalog-url>/llms-full.txt`
     - Demo: https://demo.eventcatalog.dev/llms-full.txt
 
+The ubiquitous language of your catalog is also available as [ubiquitous-language.txt](/docs/development/developer-tools/ubiquitous-language.txt).
+
 The legacy paths `/docs/llm/llms.txt` and `/docs/llm/llms-full.txt` still work for backward compatibility.
 
 ### How to use LLMS.txt?

package/dist/docs/development/{ask-your-architecture/03-schemas.txt.md → developer-tools/schemas.txt.md}

@@ -17,7 +17,7 @@ Message schemas and service specifications can be fetched from your EventCatalog
 
 ### What is schemas.txt?
 
-Schemas.txt is very similar to [LLMS.txt](/docs/development/ask-your-architecture/llms.txt), but it is specifically for schemas in your EventCatalog. 
+Schemas.txt is very similar to [LLMS.txt](/docs/development/developer-tools/llms.txt), but it is specifically for schemas in your EventCatalog. 
 
 Schemas.txt supports any schema format for your messages (e.g Avro, Protobuf, JSON Schema etc) and any specification for your services (e.g OpenAPI, AsyncAPI, GraphQL etc).
 

package/dist/docs/development/developer-tools/ubiquitous-language.txt.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 8
+keywords:
+- ubiquitous language
+- glossary
+- AI
+- LLM
+sidebar_label: ubiquitous-language.txt
+title: ubiquitous-language.txt
+description: Give AI tools the ubiquitous language of your organization
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.9.0" />
+
+Give AI tools one file with the ubiquitous language of your whole organization.
+
+### What is ubiquitous-language.txt?
+
+The file lists the terms of every domain and subdomain, with subdomains under their parent domain. It is generated from your [`ubiquitous-language.mdx`](/docs/development/guides/domains/ownership-and-language/adding-ubiquitous-language) files, so there is nothing to configure.
+
+Terms are never merged, because a word can mean different things in different domains. Terms defined in more than one domain are listed together at the top of the file, with the meaning in each domain.
+
+```txt
+## Terms defined in more than one domain
+- Reservation
+  - Fulfilment: A temporary hold on stock for a specific order, taken during checkout.
+  - Ordering: A temporary hold on stock for the items in a cart, taken during checkout.
+```
+
+Each term is one line with its summary (or its description, flattened to one line, when it has no summary). Each domain section links to that domain's `/docs/domains/{id}/language.mdx` for the full definitions.
+
+### Access the file
+
+ - `https://<your-catalog-url>/docs/llm/ubiquitous-language.txt`
+
+The file is turned on and off with the `llmsTxt` setting, the same as [llms.txt](/docs/development/developer-tools/llms.txt). When it is disabled the file returns a 404. It is linked from the LLM access settings page, and from the Ubiquitous Language section of `llms.txt`.
+
+### Use with the MCP server
+
+The [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started#available-tools) exposes the same language through the `explainUbiquitousLanguageTerms` tool.

package/dist/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md

@@ -96,5 +96,8 @@ When you add a ubiquitous language dictionary to your domain, it will automatica
 
 Clicking on a term in the Domain Language explorer will open that term in a new page. 
 
+### Share with AI tools
 
+<AddedIn version="5.9.0" />
 
+Your terms from every domain are also available to AI tools in one file, [ubiquitous-language.txt](/docs/development/developer-tools/ubiquitous-language.txt), and through the `explainUbiquitousLanguageTerms` tool of the [MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started#explain-ubiquitous-language).

package/dist/eventcatalog.cjs

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

package/dist/eventcatalog.js

@@ -7,12 +7,12 @@ import {
 import "./chunk-CA4U2JP7.js";
 import {
   log_build_default
-} from "./chunk-E636DOFG.js";
+} from "./chunk-WN6ZFSXF.js";
 import {
   getLicenseStatus,
   printLicenseStatus
 } from "./chunk-AD7CL772.js";
-import "./chunk-Z6UUCTIB.js";
+import "./chunk-26C26LFE.js";
 import "./chunk-YRZK7HKX.js";
 import "./chunk-CA6WCQ2T.js";
 import "./chunk-CPW6G62V.js";
@@ -39,10 +39,10 @@ import {
 } from "./chunk-NKNOXQ62.js";
 import {
   generate
-} from "./chunk-DT63JMNP.js";
+} from "./chunk-UIJUSHOT.js";
 import {
   logger
-} from "./chunk-WLXXZTLD.js";
+} from "./chunk-SZU7I2PD.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-PD7KTSYN.js";
@@ -79,7 +79,7 @@ import {
 } from "./chunk-LFQJXLHG.js";
 import {
   VERSION
-} from "./chunk-YU6FEGOK.js";
+} from "./chunk-C4L6B5KR.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/generate.cjs

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

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-DT63JMNP.js";
-import "./chunk-WLXXZTLD.js";
-import "./chunk-YU6FEGOK.js";
+} from "./chunk-UIJUSHOT.js";
+import "./chunk-SZU7I2PD.js";
+import "./chunk-C4L6B5KR.js";
 import "./chunk-4G7FSRPN.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 = "5.8.0";
+var version = "5.9.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-WLXXZTLD.js";
-import "../chunk-YU6FEGOK.js";
+} from "../chunk-SZU7I2PD.js";
+import "../chunk-C4L6B5KR.js";
 export {
   logger
 };

package/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx

@@ -12,10 +12,19 @@ interface Props {
   apiBase: string;
   llmsTxtUrl: string;
   llmsFullTxtUrl: string;
+  ubiquitousLanguageTxtUrl: string;
   schemasTxtUrl: string;
 }
 
-export const LlmAccessSettingsForm = ({ canEdit, initial, apiBase, llmsTxtUrl, llmsFullTxtUrl, schemasTxtUrl }: Props) => {
+export const LlmAccessSettingsForm = ({
+  canEdit,
+  initial,
+  apiBase,
+  llmsTxtUrl,
+  llmsFullTxtUrl,
+  schemasTxtUrl,
+  ubiquitousLanguageTxtUrl,
+}: Props) => {
   const [llmsTxtEnabled, setLlmsTxtEnabled] = useState(initial.llmsTxtEnabled);
   const [pristine, setPristine] = useState(initial.llmsTxtEnabled);
   const [saving, setSaving] = useState(false);
@@ -94,7 +103,9 @@ export const LlmAccessSettingsForm = ({ canEdit, initial, apiBase, llmsTxtUrl, l
             disabled={!canEdit}
             onChange={setLlmsTxtEnabled}
           />
-          {llmsTxtEnabled && <LlmsTxtPreview url={llmsTxtUrl} fullUrl={llmsFullTxtUrl} />}
+          {llmsTxtEnabled && (
+            <LlmsTxtPreview url={llmsTxtUrl} fullUrl={llmsFullTxtUrl} ubiquitousLanguageUrl={ubiquitousLanguageTxtUrl} />
+          )}
         </Row>
 
         <Row
@@ -110,10 +121,19 @@ export const LlmAccessSettingsForm = ({ canEdit, initial, apiBase, llmsTxtUrl, l
   );
 };
 
-const LlmsTxtPreview = ({ url, fullUrl }: { url: string; fullUrl: string }) => {
+const LlmsTxtPreview = ({
+  url,
+  fullUrl,
+  ubiquitousLanguageUrl,
+}: {
+  url: string;
+  fullUrl: string;
+  ubiquitousLanguageUrl: string;
+}) => {
   const variants = [
     { label: 'Index', path: url },
     { label: 'Full', path: fullUrl },
+    { label: 'Ubiquitous Language', path: ubiquitousLanguageUrl },
   ];
   return (
     <div className="rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)] px-4 py-3">

package/eventcatalog/src/features/auth/middleware/middleware-auth.ts

@@ -89,6 +89,7 @@ export function getPublicRoutes(isLLMSTextEnabled: boolean) {
     '/docs/llm/llms.txt',
     '/docs/llm/llms-full.txt',
     '/docs/llm/schemas.txt',
+    '/docs/llm/ubiquitous-language.txt',
   ];
 }