@eventcatalog/core 5.7.6 → 5.9.0

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 = "5.7.6";
+var version = "5.9.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,8 +1,8 @@
 import {
   raiseEvent
-} from "../chunk-SLN5D6WP.js";
+} from "../chunk-26C26LFE.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-E2262TPK.js";
+import "../chunk-C4L6B5KR.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

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

package/dist/analytics/log-build.js

@@ -1,12 +1,12 @@
 import {
   log_build_default
-} from "../chunk-A22MC5P5.js";
+} from "../chunk-WN6ZFSXF.js";
 import "../chunk-AD7CL772.js";
-import "../chunk-SLN5D6WP.js";
+import "../chunk-26C26LFE.js";
 import "../chunk-YRZK7HKX.js";
 import "../chunk-CA6WCQ2T.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-E2262TPK.js";
+import "../chunk-C4L6B5KR.js";
 import "../chunk-4G7FSRPN.js";
 export {
   log_build_default as default

package/dist/{chunk-SLN5D6WP.js → chunk-26C26LFE.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-CPW6G62V.js";
 import {
   VERSION
-} from "./chunk-E2262TPK.js";
+} from "./chunk-C4L6B5KR.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-E2262TPK.js → chunk-C4L6B5KR.js}

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

package/dist/{chunk-XB4U75TZ.js → chunk-SZU7I2PD.js}

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

package/dist/{chunk-UI2XA4V7.js → chunk-UIJUSHOT.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-XB4U75TZ.js";
+} from "./chunk-SZU7I2PD.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-A22MC5P5.js → chunk-WN6ZFSXF.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-AD7CL772.js";
 import {
   raiseEvent
-} from "./chunk-SLN5D6WP.js";
+} from "./chunk-26C26LFE.js";
 import {
   countResources,
   hashCatalogContent,

package/dist/constants.cjs

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

package/dist/constants.js

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

package/dist/docs/api/02-config.md

@@ -965,7 +965,7 @@ Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly underst
 }
 ```
 
-See the [LLMs documentation](/docs/development/ask-your-architecture/llms.txt) for more information, how you can use it and examples.
+See the [LLMs documentation](/docs/development/developer-tools/llms.txt) for more information, how you can use it and examples.
 
 
 ### `exports.html` {#exports.html}

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

@@ -8,13 +8,15 @@ title: Why EventCatalog?
 description: EventCatalog helps you bring discoverability to your event-driven architecture.
 ---
 
-Software architecture consists of many different primitives including [domains](/docs/development/guides/domains/introduction), [systems](/docs/development/guides/systems/introduction), [services](/docs/development/guides/resources/services/introduction), [APIs](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications), [contracts](/docs/development/guides/resources/schemas/what-are-schemas-and-specifications), [messages](/docs/development/guides/resources/messages/what-are-messages) and many more.
+As AI builds more of our systems and teams keep growing, it matters more than ever to understand how your systems connect and how they work, at every level of your organization: from the domains your business is organized around, down to a single message.
 
-As systems grow, complexity grows. Documentation becomes important for teams but teams struggle to keep docs in sync, or relevant to what they are trying to model.
+**Documentation tools today are not designed for software architecture.** They give you generic pages. They don't understand the primitives architecture is made of, such as [domains](/docs/development/guides/domains/introduction), [systems](/docs/development/guides/systems/introduction), [services](/docs/development/guides/resources/services/introduction), [APIs](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications), [contracts](/docs/development/guides/resources/schemas/what-are-schemas-and-specifications) and [messages](/docs/development/guides/resources/messages/what-are-messages), or the relationships between them. The essence of your architecture gets lost across pages that drift out of date.
 
-**Many documentation tools are not designed for software architecture**; they let you create generic pages that get lost across the organization, they do not stay in sync with your code, specifications and teams making changes.
+**Many of these tools also own your architecture knowledge.** It lives on their platform, in their format, and is hard to take with you. We believe your architecture knowledge belongs to you, inside your organization.
 
-**Our vision with EventCatalog is to change this.**
+**Our mission is to make EventCatalog the documentation tool for software architecture.** You own your data and host it internally. Your teams, people and AI alike, get an understanding of your architecture, and keep it in sync as it changes.
+
+Documentation shouldn't be where knowledge goes to die. It should be something your organization trusts, and gets value from.
 
 ### What is EventCatalog?
 
@@ -26,20 +28,22 @@ EventCatalog creates an internal [architecture graph](/docs/development/guides/a
 
 EventCatalog is technology agnostic, this means you can document and model any systems you have.
 
+**EventCatalog is self-hosted.** You run it on your own infrastructure, and your catalog lives in your own repositories. You own and control your architecture knowledge: it is never sent to us or to any third party. AI features only send content to the model provider you choose.
+
 
-#### Our project goals for you
+#### How EventCatalog can help you
 
 - **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 a documentation solution you can trust**
-  - Sync documentation from your code with the [EventCatalog Agent](/docs/development/ask-your-architecture/agents/code-to-docs)
+  - Sync documentation from your code with [EventCatalog Agents](/docs/development/agents/set-up-code-to-docs)
   - Automate documentation from your [OpenAPI](/integrations/openapi), [AsyncAPI](/integrations/asyncapi), or [schema registries](/integrations)
-  - Use EventCatalog Agent to sync code to docs from your CI/CD workflows.
+  - Use EventCatalog Agents to sync code to docs from your CI/CD workflows.
   - Write your own automation and plugins with the [EventCatalog SDK](/docs/sdk)
 - **Help you detect breaking changes before they reach production**
-  - Use EventCatalog Agent to [detect breaking schema changes](/docs/development/ask-your-architecture/agents/breaking-changes)
+  - Use EventCatalog Agents to [detect breaking schema changes](/docs/development/agents/set-up-breaking-changes)
   - Bring your own model and get notified when things break
 - **Use natural language to query your architecture**
   - Connect AI tools to your architecture using [EventCatalog's MCP server](/docs/development/ask-your-architecture/mcp-server/introduction)

package/dist/docs/development/01-adopting-eventcatalog.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 2.5
+slug: /development/getting-started/adopting-eventcatalog
+keywords:
+- EventCatalog adoption
+- rollout
+- champion
+- Federation
+sidebar_label: Adopting EventCatalog
+title: Adopting EventCatalog in your organization
+description: How organizations usually adopt EventCatalog, from one champion and one pain point to a catalog that grows across teams.
+---
+
+import { RolloutJourney } from '@site/src/components/Rollout';
+import { OrgTopology } from '@site/src/components/AgentOutputs';
+
+Most organizations adopt EventCatalog step by step. This is the pattern we see most often.
+
+<RolloutJourney />
+
+## 1. Start with a champion
+
+A champion drives EventCatalog in your organization. It can be one person or a team. They set up the first catalog, and help other teams start using it.
+
+## 2. Solve one pain point
+
+The champion picks one workflow or pain point, and documents around it. For example, teams can't find the schemas for your events, so the first catalog documents your events and their schemas.
+
+Starting small means the catalog is useful from day one, and you learn what your organization needs from it.
+
+## 3. Share it and get feedback
+
+Once the pain point is solved, share the catalog with other teams and ask for feedback. Teams will tell you what they want to see next, and some will start contributing.
+
+## 4. Grow your catalog over time
+
+Build the catalog up over time: add [domains](/docs/development/guides/domains/introduction), [systems](/docs/development/guides/systems/introduction), services, [flows](/docs/development/guides/resources/flows/introduction) and owners. The more you add, the more your catalog connects, and the more valuable it becomes.
+
+To keep it up to date as it grows, generate parts of it from your [specifications and schema registries](/integrations), and keep it in sync with your code with [EventCatalog Agents](/docs/development/agents/set-up-code-to-docs).
+
+## One catalog, or many
+
+You can have one catalog for your whole organization, or a catalog per team combined with [Federation](/docs/federation/overview). With Federation, each team controls its own documentation, and you still get one view of your whole architecture.
+
+<OrgTopology />
+
+Most organizations start with one central catalog and a couple of champions, then roll it out to more teams.
+
+## Talk to us
+
+If you want to discuss how to roll out EventCatalog in your organization, [contact us at hello@eventcatalog.dev](mailto:hello@eventcatalog.dev). We're happy to walk you through the options and advise you.

package/dist/docs/development/{ask-your-architecture/03-install-skills.md → 01-getting-started/install-skills.md}

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 3.5
 keywords:
 - AI Skills
 - Claude Code
@@ -26,15 +26,21 @@ With skills installed, you can ask your agent things like:
 - "Create a Payments domain with a PaymentService, PaymentProcessed event, and ProcessPayment command"
 - "Look at my src/ directory and generate EventCatalog documentation for the services and events you find"
 - "Document the checkout flow from cart submission through payment processing to order confirmation"
+- "Use this Structurizr DSL file to map our C4 model into my catalog"
+- "Write a fitness function that fails CI when two services share a database"
 
 The agent will generate properly formatted `index.mdx` files with correct frontmatter, schemas, and visualizations.
 
 ## Available skills
 
-| Skill | Description |
+| Skill | What it does |
 |-------|-------------|
-| [Catalog Documentation Creator](https://github.com/event-catalog/skills) | Generates EventCatalog documentation files (services, events, commands, queries, domains, flows, channels, containers) with correct frontmatter, folder structure, and best practices. |
-| [Flow Wizard](https://github.com/event-catalog/skills) | Guides you through documenting a business flow step by step in a conversational session, cross-referencing your existing catalog resources to link services, events, and commands automatically. |
+| [Catalog Documentation Creator](https://github.com/event-catalog/skills/tree/main/skills/catalog-documentation-creator) | Generates EventCatalog documentation (domains, systems, services, agents, messages, channels, flows, data stores, ADRs, data products and entities) with the correct frontmatter, folder structure and best practices. Code to Catalog and C4 to EventCatalog use it to write their files. |
+| [Code to Catalog](https://github.com/event-catalog/skills/tree/main/skills/code-to-catalog) | Scans your codebase, proposes an architecture model, asks you about the decisions it can't work out from the code, and writes a plan before documenting it. Works for new catalogs, and for catalogs that have drifted from the code. |
+| [C4 to EventCatalog](https://github.com/event-catalog/skills/tree/main/skills/c4-to-eventcatalog) | Maps a C4 model (Structurizr, LikeC4, C4-PlantUML, Mermaid C4, or a diagram) into your catalog. |
+| [Flow Wizard](https://github.com/event-catalog/skills/tree/main/skills/flow-wizard) | Documents a business or agent flow step by step in a conversation, linking the services, agents and messages already in your catalog. |
+| [Fitness Functions](https://github.com/event-catalog/skills/tree/main/skills/fitness-functions) | Turns an architecture rule you describe in plain language into a [fitness function](/docs/development/guides/fitness-functions/what-are-fitness-functions), runs it, and adds it to your CI. |
+| [Custom Pages and APIs](https://github.com/event-catalog/skills/tree/main/skills/custom-pages-and-apis) | Builds custom pages and API routes inside your catalog, with access to your catalog's data, and adds them to the navigation. |
 
 ## Install skills
 

package/dist/docs/development/01-getting-started/installation.md

@@ -7,10 +7,14 @@ title: Installation
 description: Install EventCatalog and create a new catalog
 ---
 
+import { AgentPrompt } from '@site/src/components/AgentPrompt';
+
 The `create-eventcatalog` CLI command is the fastest way to start a new EventCatalog project. It creates a catalog directory, installs what you need, and gives you scripts for local development and production builds.
 
 You can also start from a template, create an empty catalog, or use the EventCatalog AI skill to generate documentation from an existing codebase.
 
+<AgentPrompt />
+
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/en/download/) v22 or higher. Check your version with `node -v`.
@@ -100,7 +104,7 @@ Then ask your AI agent to inspect your codebase and generate EventCatalog docume
 Look at my directory and generate EventCatalog documentation from information you find.
 ```
 
-The generated files can be edited like any other EventCatalog documentation. Learn more about [EventCatalog skills](/docs/development/ask-your-architecture/install-skills).
+The generated files can be edited like any other EventCatalog documentation. Learn more about [EventCatalog skills](/docs/development/getting-started/install-skills).
 
 ## Optional: Use EventCatalog Editor
 

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

@@ -11,11 +11,13 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 EventCatalog creates an internal graph of your architecture. Perfect for AI and LLMs.
 
-EventCatalog supports six ways to use AI with your catalog:
+EventCatalog supports eight ways to use AI with your catalog:
 
 - [EventCatalog MCP Server](/docs/development/ask-your-architecture/mcp-server/introduction) - Connect EventCatalog to Agents through MCP
-- [AI Skills](/docs/development/ask-your-architecture/install-skills) - Install our Skills to help you manage your catalog
-- [EventCatalog Agent](/docs/development/ask-your-architecture/agents/overview) - CI/CD Agent for breaking changes and doc updates
 - [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant) - AI Chat in your Catalog.
-- [llms.txt](/docs/development/ask-your-architecture/llms.txt) - Give AI tools a machine-readable index of your catalog.
-- [schemas.txt](/docs/development/ask-your-architecture/schemas.txt) - Give AI tools access to your schemas and specifications.
+- [Sync docs with your code](/docs/development/agents/set-up-code-to-docs) - EventCatalog Agents keep your catalog in sync with your code
+- [Catch breaking changes](/docs/development/agents/set-up-breaking-changes) - EventCatalog Agents warn you before a schema change breaks a consumer
+- [AI Skills](/docs/development/getting-started/install-skills) - Install our Skills to help you manage your catalog
+- [llms.txt](/docs/development/developer-tools/llms.txt) - Give AI tools a machine-readable index of your catalog.
+- [schemas.txt](/docs/development/developer-tools/schemas.txt) - Give AI tools access to your schemas and specifications.
+- [ubiquitous-language.txt](/docs/development/developer-tools/ubiquitous-language.txt) - Give AI tools the ubiquitous language of your organization.

package/dist/docs/development/ask-your-architecture/03-mcp-server/getting-started.md

@@ -63,7 +63,7 @@ or system.
 
 :::note Scoped tool availability
 Scoped servers omit C4, team and user directory, data product, custom documentation, and user-defined extended tools.
-System-scoped servers also omit the domain-specific ubiquitous-language tool. See [Available tools](#available-tools).
+System-scoped servers also omit the ubiquitous-language tool. See [Available tools](#available-tools).
 :::
 
 ### Disable the MCP server
@@ -254,7 +254,7 @@ wants to see a diagram or schema.
 | `analyzeChangeImpact` | Analyze the impact of changing a message | Returns the affected producers and consumers, their owning teams and the blast radius of a change | Yes |
 | `explainBusinessFlow` | Explain a business flow | Returns a flow's definition, steps and related services and agents | Yes |
 | `findMessageBySchemaId` | Find a message from a schema | Finds a message from the `x-eventcatalog-id` (and optional `x-eventcatalog-version`) in a schema | Yes |
-| `explainUbiquitousLanguageTerms` | Explain ubiquitous language terms | Returns the ubiquitous language terms of a domain and its subdomains | Domain servers only |
+| `explainUbiquitousLanguageTerms` | Explain ubiquitous language terms | Returns ubiquitous language terms. See [Explain ubiquitous language](#explain-ubiquitous-language) | Domain servers only |
 | `getC4Diagram` | Get C4 (LikeC4) diagrams | Returns the source of your C4 (LikeC4) diagrams | No |
 | `getTeams` / `getTeam` | List teams / Get a team | Lists teams, or gets a team with its members | No |
 | `getUsers` / `getUser` | List users / Get a user | Lists users, or gets a user with their role and contact details | No |
@@ -269,6 +269,20 @@ wants to see a diagram or schema.
 In clients that support MCP Apps, the server also registers `getResourceView`. The viewer uses this app-only tool to load
 diagrams and schemas. The model doesn't call it.
 
+### Explain ubiquitous language
+
+<AddedIn version="5.9.0" />
+
+`explainUbiquitousLanguageTerms` has no required parameters. Each term returns its `id`, `summary` and full `description` (the summary when there is no description).
+
+| Parameters | Returns |
+|---|---|
+| `domainId` | The terms of that domain and its subdomains |
+| `term` | Each domain's meaning of the term, kept separate. Matches the term's name or id, case-insensitive |
+| none | The whole glossary |
+
+Use `cursor` to page through results when looking across every domain. Domain-scoped servers stay inside their domain: with no `domainId` they use the scoped domain, and another domain returns an error.
+
 ### Interactive diagrams and schemas
 
 <AddedIn version="5.0.0" />
@@ -357,7 +371,7 @@ For catalogs without SSR mode, use the standalone `@eventcatalog/mcp-server` pac
 For local development and testing, you can use the MCP Server on stdio. This is useful for single-client, low-latency tools.
 
 **Prerequisites:**
-- EventCatalog configured with the [`LLMS.txt` feature](/docs/development/ask-your-architecture/llms.txt)
+- EventCatalog configured with the [`LLMS.txt` feature](/docs/development/developer-tools/llms.txt)
 - EventCatalog license key
 - MCP client installed
 

package/dist/docs/development/ask-your-architecture/03-mcp-server/introduction.md

@@ -8,11 +8,14 @@ description: Connect AI tools to your architecture catalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import { McpFlow } from '@site/src/components/McpFlow';
 
 EventCatalog exposes a built-in MCP server that lets AI agents and other MCP clients query your architecture catalog. Its
 built-in tools can find resources, inspect schemas and ownership, follow message producers and consumers, and analyze change
 impact.
 
+<McpFlow />
+
 You can connect a client to the whole catalog, or limit it to the graph of a particular domain or system. Scoped connections
 give an agent the selected resource and resources recursively reachable through its supported relationships, without exposing
 unrelated parts of the catalog.

package/dist/docs/development/ask-your-architecture/06-sync-docs-with-your-code.md

@@ -0,0 +1,220 @@
+---
+sidebar_position: 6
+keywords:
+  - Code-to-Docs
+  - EventCatalog Agents
+  - documentation automation
+  - docs drift
+  - GitHub Actions
+sidebar_label: Sync docs with your code
+title: Sync docs with your code
+description: The Code-to-Docs workflow updates your EventCatalog when a pull request changes your architecture, and opens a pull request in your catalog for your team to review.
+slug: /development/agents/set-up-code-to-docs
+---
+
+import { AgentFlow, CodeToDocsComment, OrgTopology } from '@site/src/components/AgentOutputs';
+import { AgentPrompt } from '@site/src/components/AgentPrompt';
+
+The **Code-to-Docs** workflow turns your catalog into self-updating knowledge of your architecture. When a pull request changes your architecture, it updates the docs the change affects, and opens a pull request in your catalog for your team to review.
+
+<AgentPrompt variant="code-to-docs" />
+
+Docs that drift stop being used. When your catalog matches what's running, engineers can trust it to answer questions without reading the code, and AI tools that read your catalog get the right answers too.
+
+- **Bring your own model.** Use any model you want, with your own key. You pay your provider directly.
+- **Your data stays private.** It runs in your own CI and sends code only to your model provider. We never see your code or your catalog.
+- **Your own workflow.** You decide which repositories update which catalog, when, and who approves the changes.
+
+## How it works
+
+<AgentFlow />
+
+1. **Reads the change.** The agent reads the pull request's diff and the code around it, and finds the affected resources in your catalog.
+2. **Plans.** It decides which resources need to change and why. If nothing needs to change, it says so and stops.
+3. **Updates your catalog.** It edits only the resources in its plan, the way your catalog is already written. If it edits a file outside its plan, the run stops and nothing is pushed.
+4. **Checks its work.** It runs the EventCatalog linter and your [fitness functions](/blog/architecture-fitness-functions), and fixes the problems it caused. It never edits fitness functions.
+5. **Opens a pull request** in your catalog, and comments on your pull request with a link to it.
+
+The agent can get things wrong, so review every catalog pull request.
+
+## Before you start
+
+You need:
+
+- An EventCatalog in a GitHub repository (the **catalog repository**), with the catalog at the root of the repository.
+- A repository with code to document (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, push branches to it and open pull requests. Or [use a GitHub App](#use-a-github-app).
+
+Then add the workflow:
+
+```yaml title=".github/workflows/eventcatalog.yml"
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  code-to-docs:
+    # Only once the pull request is merged.
+    if: github.event.pull_request.merged == true
+    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: code-to-docs
+          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, merge a pull request that changes your architecture, such as a new event or a changed schema. The agent opens a pull request in your catalog, and comments on your pull request:
+
+<CodeToDocsComment />
+
+## Choose when it runs
+
+We recommend running Code-to-Docs **when a pull request merges**, as above. It documents what shipped, runs once per pull request, and never documents abandoned work. A pull request closed without merging is skipped.
+
+To show the catalog update to reviewers next to the code, run it **while the pull request is open** instead:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+```
+
+| | When the pull request merges | While the pull request is open |
+| --- | --- | --- |
+| Catalog pull request appears | After the merge | Before the merge, next to the code |
+| Agent runs | Once per pull request | On every push |
+| Abandoned pull requests | Never documented | Leave a catalog pull request for you to close |
+
+Use `pull_request` events, not `push` to your main branch. The agent needs the pull request to compare it with its base branch and to comment on it.
+
+## Use it across your organization
+
+<OrgTopology />
+
+- **One catalog for the organization.** Add the workflow to each repository with the same `catalog-repo`. The agent puts each change in the right domain and system.
+- **A catalog per team.** Point each repository's `catalog-repo` at its team's catalog. [Federation](/docs/federation/overview) combines the team catalogs into one organization-wide catalog.
+
+**Choose who reviews.** Catalog updates are pull requests, so your branch protection, required reviews and code owners apply. To send each update to the team that owns that part of the catalog, add a `CODEOWNERS` file to your catalog repository:
+
+```text title=".github/CODEOWNERS"
+/domains/Payments/  @acme/payments-platform
+/domains/Orders/    @acme/ordering-platform
+```
+
+**Set up many repositories at once.** Keep the workflow in one place as a [reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows), and call it from each repository:
+
+```yaml title=".github/workflows/eventcatalog.yml in each repository"
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  eventcatalog:
+    if: github.event.pull_request.merged == true
+    uses: acme/.github/.github/workflows/eventcatalog-agents.yml@main
+    secrets: inherit
+```
+
+Use [organization secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-organization) for your model provider key, and a [GitHub App](#use-a-github-app) instead of a personal token.
+
+## Configuration
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | No | `code-to-docs` | The workflow to run. This workflow is the default. |
+| `catalog-repo` | Yes | | Your catalog repository, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | The catalog branch to read, and to open pull requests against. |
+| `catalog-token` | No | `github.token` | A token that can read the catalog repository, push branches to it and open pull requests. |
+| `github-app-client-id` | No | | Client ID of a [GitHub App](#use-a-github-app). Used instead of `catalog-token`. |
+| `github-app-private-key` | No | | The private key of that GitHub App. Pass it from a secret. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | The model the agent uses. See [models](#models). |
+| `ignore-paths` | No | Build and dependency folders | Comma-separated paths or glob patterns to leave out of the review. |
+
+By default, `ignore-paths` leaves out folders such as `node_modules`, `dist` and `build`. Your list replaces the defaults, so keep the folders you still want left out:
+
+```yaml
+with:
+  ignore-paths: node_modules,dist,build,src/generated,**/*.test.ts
+```
+
+## 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` |
+
+We test with `anthropic/claude-sonnet-4-6`, the default. Smaller models are cheaper, but follow your catalog's conventions less reliably.
+
+To use models in your own AWS account, use an `amazon-bedrock/` model and give the job AWS credentials. Your code is then sent only to Bedrock, in the region you choose:
+
+```yaml
+permissions:
+  id-token: write # for AWS OIDC
+  contents: read
+  issues: write
+  pull-requests: write
+steps:
+  - uses: aws-actions/configure-aws-credentials@v4
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/eventcatalog-agents
+      aws-region: eu-west-1
+  - uses: event-catalog/agents@v2
+    with:
+      agent: code-to-docs
+      catalog-repo: your-org/your-catalog
+      catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+      model: amazon-bedrock/eu.anthropic.claude-sonnet-4-6
+```
+
+## Use a GitHub App
+
+Instead of a personal access token, you can give the agent a GitHub App. Catalog pull requests then come from the App's bot account, there's no personal token to replace when someone leaves, and each run gets a token that only works on the catalog repository and expires after an hour.
+
+1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) in your organization with **Contents** and **Pull requests** set to **Read and write**. Turn off the webhook.
+2. Generate a **private key**, and install the App on your catalog repository.
+3. In your source repository, save the App's **Client ID** as a variable and its private key as a secret, and pass them instead of `catalog-token`:
+
+```yaml
+with:
+  agent: code-to-docs
+  catalog-repo: your-org/your-catalog
+  github-app-client-id: ${{ vars.EVENTCATALOG_APP_CLIENT_ID }}
+  github-app-private-key: ${{ secrets.EVENTCATALOG_APP_PRIVATE_KEY }}
+```
+
+## Data and privacy
+
+- **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.
+- **It only changes your catalog through pull requests**, on branches named `eventcatalog-actions/...`. It never pushes to your catalog's main branch.
+- **Your catalog's tools run without your secrets.** The linter and your fitness functions run as separate processes, without your model provider key or GitHub tokens.
+
+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, the repository name, and how many of the agent's catalog pull requests are open, merged or closed. 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).