@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+keywords:
+  - Code to Docs
+  - AI Agents
+  - GitHub Action
+  - documentation generation
+sidebar_label: Code-to-Docs Agent
+title: Code-to-Docs Agent
+description: Keep your EventCatalog documentation in sync with your code using the Code-to-Docs agent
+---
+
+The **Code-to-Docs** agent keeps your EventCatalog documentation in sync with your code.
+
+When you open a pull request, the agent reviews the diff, works out which documentation should change, updates it in your catalog repository, and opens (or updates) a documentation pull request. It then comments back on your source pull request with a summary and a link.
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[Source pull request] --> Agent[Code-to-Docs agent]
+    Agent --> Plan{Docs need<br/>updating?}
+    Plan -- No --> Comment[Comment on source PR]
+    Plan -- Yes --> Docs[Update catalog docs]
+    Docs --> CatalogPR[Open catalog pull request]
+    CatalogPR --> Comment
+```
+
+When a pull request is opened, the agent:
+
+1. **Checks out your catalog** so it can see your existing documentation.
+2. **Collects the changed source files** from the pull request.
+3. **Plans the impact**. A read-only pass where the agent decides whether the diff requires any documentation changes, and if so, exactly which catalog resources should change. If nothing is needed, it stops here and says so.
+4. **Applies the plan**. The agent updates the documentation, using EventCatalog conventions for frontmatter and folder structure, and a linter to validate its changes. It is only allowed to touch the resources approved in the plan.
+5. **Opens a catalog pull request** with the changes for you to review.
+6. **Comments on your source pull request** with a high-level summary and a link to the catalog pull request.
+
+You stay in control: the agent never edits your catalog silently. Every change arrives as a pull request you can review, tweak, and merge.
+
+## Getting started
+
+The Code-to-Docs agent runs as a GitHub Action. Add it to your repository in three steps.
+
+### 1. Add a new GitHub workflow
+
+Create a new workflow in your source directory. Typically this is where your source code lives (e.g a service that publishes/consumes messages).
+
+Create a `.github/workflows/eventcatalog.yml` file.
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  eventcatalog:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: event-catalog/agents@main
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          agent: code-to-docs
+          catalog-repo: your-org/your-catalog
+          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+`fetch-depth: 0` is required so the agent can diff the pull request against its base.
+
+### 2. Add your model provider key
+
+Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+
+You can see the list of [available models here](https://pi.dev/models).
+
+### 3. Open a pull request
+
+When you next open a pull request on your project, the EventCatalog Agent will run.
+
+If your architecture changed, opens a documentation pull request in your catalog repository and comments back with a link.
+
+## Configuration
+
+### Inputs
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `catalog-repo` | Yes | | The location of your hosted EventCatalog. EventCatalog repository to document into, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | Branch checked out from the catalog repository and targeted by documentation pull requests. |
+| `catalog-token` | No | `github.token` | Token used to check out the catalog repository and open documentation pull requests. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
+| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
+| `agent` | No | `code-to-docs` | Which EventCatalog agent to run. Use `code-to-docs` for this workflow. |
+
+### Provider API keys
+
+The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
+
+| Provider | Environment variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
+
+### Documenting into a separate catalog repository
+
+When your catalog lives in a **different** repository from your source code, provide a `catalog-token` with permission to push branches and open pull requests in that catalog repository (the default `github.token` only has access to the current repository).
+
+:::info Early access
+The Code-to-Docs agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
+:::
+
+## Found an issue or have feedback?
+
+The Code-to-Docs agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent documents something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.

package/dist/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md

@@ -0,0 +1,170 @@
+---
+sidebar_position: 3
+keywords:
+  - Breaking Changes
+  - AI Agents
+  - GitHub Action
+  - schema governance
+  - schema compatibility
+sidebar_label: Breaking Changes Agent
+title: Breaking Changes Agent
+description: Detect breaking schema changes and affected EventCatalog consumers from pull requests
+---
+
+The **Breaking Changes** agent reviews schema changes in pull requests and reports whether they are likely to break existing consumers.
+
+When a pull request changes a message schema, the agent checks whether the diff removes or renames fields, changes types, adds new required fields, narrows enums, or introduces similar compatibility risks. If it finds a breaking change, it traces the schema through your EventCatalog and comments on the source pull request with the breaking lines and affected consumers.
+
+The Breaking Changes agent is read-only. It does not edit your catalog or open documentation pull requests.
+
+![Breaking Changes agent pull request comment showing detected schema changes and affected consumers](./img/breaking-changes-agent.jpeg)
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[Source pull request] --> Agent[Breaking Changes agent]
+    Agent --> Schema{Schema<br/>changed?}
+    Schema -- No --> Skip[Nothing to report]
+    Schema -- Yes --> Breaking{Breaking<br/>change?}
+    Breaking -- No --> Skip
+    Breaking -- Yes --> Consumers[Find catalog consumers]
+    Consumers --> Comment[Comment on source PR]
+```
+
+When a pull request is opened, the agent:
+
+1. **Checks out your catalog** so it can understand the existing producers, consumers, messages, schemas, and flows.
+2. **Collects the changed source files** from the pull request.
+3. **Filters to schema files** using the configured schema extensions.
+4. **Scores each schema change** for breaking-change risk. Additive changes, such as adding an optional field, are skipped.
+5. **Finds affected consumers** for each breaking schema change by tracing the message through EventCatalog.
+6. **Comments on your source pull request** with the breaking change, the relevant diff lines, and the consumers that could be affected.
+
+If the pull request has no changed schema files, or only non-breaking schema changes, the workflow exits without creating a catalog pull request.
+
+## Getting started
+
+The Breaking Changes agent runs as a GitHub Action.
+
+### 1. Add a new GitHub workflow
+
+Create a `.github/workflows/eventcatalog-breaking-changes.yml` file in the repository where your source changes happen.
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  eventcatalog-breaking-changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: event-catalog/agents@main
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          agent: breaking-changes
+          catalog-repo: your-org/your-catalog
+          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+`fetch-depth: 0` is required so the agent can diff the pull request against its base.
+
+### 2. Add your model provider key
+
+Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+
+You can see the list of [available models here](https://pi.dev/models).
+
+### 3. Open a pull request that changes a schema
+
+When a pull request changes a schema, the agent reviews the schema diff. If it finds a breaking change, it comments on the pull request with the affected EventCatalog consumers.
+
+## Configuration
+
+### Inputs
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | No | `code-to-docs` | Set this to `breaking-changes` to run the Breaking Changes agent. |
+| `catalog-repo` | Yes | | The EventCatalog repository to inspect, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | Branch checked out from the catalog repository. |
+| `catalog-token` | No | `github.token` | Token used to check out the catalog repository. Use a token with read access when the catalog is in another private repository. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
+| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
+| `schema-extensions` | No | `.json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql` | Comma-separated file extensions the agent treats as message schemas. |
+
+### Schema extensions
+
+By default, the agent checks common schema files:
+
+```yaml
+schema-extensions: .json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql
+```
+
+If your message contracts live in another file type, add that extension:
+
+```yaml
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: breaking-changes
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+    schema-extensions: .json,.yaml,.ts
+```
+
+Only add source-code extensions when those files contain message contracts. The agent ignores non-schema files for this workflow.
+
+### Provider API keys
+
+The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
+
+| Provider | Environment variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
+
+## Run with Code-to-Docs
+
+Each Action step runs one EventCatalog agent. To run Breaking Changes and [Code-to-Docs](/docs/development/ask-your-architecture/agents/code-to-docs) on the same pull request, add two steps:
+
+```yaml
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: breaking-changes
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: code-to-docs
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+Use Breaking Changes when you want pull request feedback about schema compatibility. Use Code-to-Docs when you want catalog documentation updates proposed as a separate pull request.
+
+:::info Early access
+The Breaking Changes agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
+:::
+
+## Found an issue or have feedback?
+
+The Breaking Changes agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent reports something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.

package/dist/docs/development/ask-your-architecture/04-agents/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Agents",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/ask-your-architecture/agents",
+    "title": "EventCatalog Agents",
+    "description": "AI agents that help you manage and document your architecture with EventCatalog."
+  }
+}

package/dist/docs/development/ask-your-architecture/{04-skills → 05-skills}/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Skills",
-  "position": 4,
+  "position": 7,
   "collapsible": true,
   "collapsed": true,
   "link": {
@@ -8,4 +8,4 @@
     "slug": "/development/ask-your-architecture/skills",
     "description": "Pre-built AI skills for generating EventCatalog documentation"
   }
-}
+}

package/dist/docs/development/ask-your-architecture/{05-slack-integration → 06-slack-integration}/03-installation.md

@@ -164,6 +164,6 @@ ai: {
 
 ## License key
 
-Get your EventCatalog Scale license key from [eventcatalog.cloud](https://eventcatalog.cloud). A 14-day free trial is available.
+Get your EventCatalog Scale license key from [eventcatalog.cloud](https://eventcatalog.cloud). A 30-day free trial is available.
 
 The license key must be set as the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable.

package/dist/docs/development/ask-your-architecture/{05-slack-integration → 06-slack-integration}/_category_.json

@@ -1,6 +1,7 @@
 {
   "label": "Slack Integration",
-  "position": 5,
+  "position": 8,
+  "className": "hidden",
   "collapsible": true,
   "collapsed": true,
   "link": {

package/dist/docs/development/ask-your-architecture/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Agents with EventCatalog",
-  "position": 8,
+  "label": "AI with EventCatalog",
+  "position": 6,
   "collapsible": false,
   "collapsed": false,
   "link": {

package/dist/docs/development/authentication/01-introduction.md

@@ -8,11 +8,11 @@ description: Introduction to EventCatalog Authentication
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 # Authentication Guide
 
-<EventCatalogPro />
+<PlanBanner plan="Scale" />
 <AddedIn version="2.43.0" />
 
 
@@ -67,7 +67,7 @@ Designed for large organizations with dedicated identity management systems:
 
 Ready to secure your EventCatalog with authentication?
 
-**New to EventCatalog?** Start your **14-day free trial** at [EventCatalog.cloud](https://eventcatalog.cloud) to explore all authentication features.
+**New to EventCatalog?** Start your **30-day free trial** at [EventCatalog.cloud](https://eventcatalog.cloud) to explore all authentication features.
 
 ## Next steps
 

package/dist/docs/development/authentication/02-enabling-authentication.md

@@ -23,7 +23,7 @@ To enable authentication for your site, you will need to do three things:
 :::info Authentication is a paid feature
 Authentication is a paid feature, and is available on EventCatalog Scale and Enterprise plans.
 
-You can get a 14 day free trial of EventCatalog Scale and Enterprise [here](https://www.eventcatalog.dev/pricing).
+You can get a 30-day free trial of EventCatalog Scale and Enterprise [here](https://www.eventcatalog.dev/pricing).
 
 You will need to set your license key in your `.env` file.
 
@@ -44,7 +44,7 @@ This is the only strictly required environment variable. It is the secret used t
 AUTH_SECRET=your-secret
 ```
 
-#### AUTH_TRUST_HOST
+#### AUTH_TRUST_HOST {#auth_trust_host}
 
 When running EventCatalog behind a reverse proxy (Kubernetes/AKS, Nginx, Cloudflare, AWS ALB, etc.), you must set `AUTH_TRUST_HOST=true`. Without it, Auth.js falls back to the internal container URL (e.g. `http://localhost:3000`) instead of the real domain, which causes login and sign-out to fail with CSRF/cross-site errors such as "Cross-site POST form submissions are forbidden".
 

package/dist/docs/development/authentication/providers/03-setting-up-github.md

@@ -8,7 +8,6 @@ description: Setting up GitHub authentication for EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
 import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.43.0" />
@@ -73,6 +72,31 @@ All pages should now be protected and require a GitHub account to access.
 
 ![GitHub authentication](./img/github-auth.png)
 
+## Running behind a reverse proxy (`redirectProxyUrl`)
+
+When running behind a reverse proxy or load balancer (Kubernetes/AKS, Nginx, Cloudflare, AWS ALB/ECS, etc.), GitHub sign-in can break with:
+
+> The redirect_uri is not associated with this application.
+
+This happens when the OAuth `redirect_uri` ends up as `http://` (or an internal host) instead of your real `https://` URL, because the proxy terminates TLS and forwards the request internally. You may also see `InvalidCheck: pkceCodeVerifier value could not be parsed` in your logs from the same wrong base URL.
+
+[`AUTH_TRUST_HOST=true`](/docs/development/authentication/enabling-authentication#auth_trust_host) fixes this for most setups. If your proxy doesn't reliably forward the `x-forwarded-host` / `x-forwarded-proto` headers, set `redirectProxyUrl` to your canonical public URL to force the correct callback:
+
+```js title="eventcatalog.auth.js"
+export default {
+  providers: {
+    github: {
+      clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+      clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+      // Canonical public URL of your site, including /api/auth
+      redirectProxyUrl: 'https://catalog.example.com/api/auth',
+    },
+  },
+};
+```
+
+The host must match the **Authorization callback URL** on your GitHub OAuth app (`https://catalog.example.com/api/auth/callback/github`). Not needed on Vercel, Cloudflare Pages, or local dev. See the [Auth.js reference](https://authjs.dev/reference/core#redirectproxyurl) for more.
+
 ## Found an issue?
 
 Remember to setup the prerequisites for this guide:

package/dist/docs/development/authentication/providers/03a-setting-up-google.md

@@ -9,7 +9,6 @@ id: setting-up-google
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
 import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.43.3" />

package/dist/docs/development/bring-your-own-documentation/01-introduction.md

@@ -7,44 +7,48 @@ title: Bring your own documentation
 description: Bring your own documentation to EventCatalog
 ---
 
-EventCatalog allows you to centralise architecture documentation alongside your domains, services, and events — keeping knowledge and context in one place.
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-You can write this documentation with Markdown and MDX, or use the optional [EventCatalog Editor](/docs/editor/overview) for a visual editing workflow.
+<PlanBanner plan="Scale" />
 
-Common use cases include:
+EventCatalog lets you bring your own documentation and diagrams into your catalog.
 
-- Architecture decision records (ADRs)
-- Infrastructure & operations runbooks
-- CI/CD documentation
-- User journeys
-- API documentation
-- Technical debt tracking
-- Team processes
-- Onboarding information
-- Best practices & standards
+This is useful when your documentation is spread across multiple repositories, project folders, wikis, or internal tools. You can bring that context into EventCatalog and make it part of the same experience people already use to explore your architecture.
 
-EventCatalog provides two ways to bring your own documentation to your catalog:
+You can document anything that helps your teams understand, operate, and govern your systems, including:
 
-1. [Global documentation](#1-global-documentation) 
-   - for cross-cutting and catalog-wide knowledge
-2. [Resource-level documentation](#2-resource-level-documentation) 
-   - for implementation details tied to a specific resoruce (e.g domain, service, or event)
+- Team onboarding documentation
+- Best practices and engineering standards
+- Runbooks and operational guides
+- CI/CD and deployment documentation
+- User journeys and business processes
+- Technical debt and migration notes
+
+EventCatalog has a few ways to bring your own information to your catalog:
+
+1. [High level documentation](#high-level-documentation)
+   - for catalog-wide knowledge that is not tied to one specific resource
+1. [Resource-level documentation](#resource-level-documentation)
+   - for documentation attached to a specific domain, service, event, API, or other catalog resource
+1. [Diagrams](/docs/development/bring-your-own-documentation/diagrams/introduction)
+   -  bring your own diagrams (e.g Miro, DrawIO, Mermaid) to your catalog.
 
 ---
 
-### Global documentation
+### High level documentation
+
+High level documentation is for top-level knowledge that should live in your catalog but does not belong to one specific resource.
 
-Global documentation can be used to document cross-cutting and catalog-wide knowledge. 
-You can bring your own documentation to your catalog and have your own documentation section (/docs/custom/) regardless of EventCatalog resources.
+Use high level documentation for things like engineering standards, onboarding guides, architecture principles, platform runbooks, team processes, or shared API guidance. These pages appear in your catalog's documentation area and can be organized independently from your domains, services, and events.
 
-[Read the custom pages guide](/docs/guides/bring-your-own-documentation/custom-pages).
+[Read the high level documentation guide](/docs/development/bring-your-own-documentation/custom-pages/introduction).
 
 ### Resource-level documentation
 
-Resource-level documentation can be used to document implementation details tied to a specific EventCatalog resource (e.g domain, service, or event).
+Resource-level documentation is for knowledge that belongs with a specific EventCatalog resource.
 
-This can be useful if you want to document details tied to a specific domain, service, message, data product, etc.
+Use resource-level documentation when the context should appear next to the thing it describes. For example, you can attach service runbooks to a service, onboarding material to a domain, operational notes to a system, or extra API documentation to an API.
 
-EventCatalog will render your custom documentation alongside the resource it is tied to in the sidebar.
+EventCatalog renders this documentation alongside the resource, so readers can move between the resource overview and its supporting documentation without leaving the catalog.
 
-[Read the resource docs guide](/docs/guides/bring-your-own-documentation/resource-docs).
+[Read the resource-level documentation guide](/docs/development/bring-your-own-documentation/resource-docs/introduction).

package/dist/docs/development/bring-your-own-documentation/custom-pages/01-introduction.md

@@ -8,14 +8,16 @@ description: Customize documentation in EventCatalog
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
 
 <iframe width="100%" height="415" src="https://www.youtube.com/embed/auzmEf0AdJg?si=wHe-3X6b6uLN39sB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ---
 
-Global documentation is a way to add catalog-wide custom documentation pages to your catalog.
+High level documentation is a way to add catalog-wide custom documentation pages to your catalog.
 
 This can be a great way to extend your catalog beyond what is provided, and bring your own documentation to EventCatalog, rather than having documentation spread across multiple tools.
 
@@ -23,9 +25,8 @@ This can be a great way to extend your catalog beyond what is provided, and brin
 ![Example](./img/custom-docs.png)
 <a class="block" href="https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern">View demo</a>
 
-Global documentation is not limited, here are some examples of what you can do:
+High level documentation is not limited, here are some examples of what you can do:
 
-- Document architecture decision records
 - Document infrastructure & operations
 - Document CI/CD pipelines
 - Document user journeys
@@ -38,23 +39,23 @@ Global documentation is not limited, here are some examples of what you can do:
 
 It's really up to you what you add here.
 
-### How global documentation can help
+### How high level documentation can help
 
 EventCatalog provides the ability to document your architecture with domains, services and messages. 
 
 Users still have third party tools to document other parts of their architecture (e.g confluence, Google docs, etc), so this is an option to help you keep all your documentation in one place.
 
-### What can I do with global documentation in EventCatalog?
+### What can I do with high level documentation in EventCatalog?
 
 You can add any custom documentation to your catalog, this also gives you access to the [EventCatalog components](/docs/components).
 Your custom documentation is powered by markdown, meaning you can use EventCatalog components within your documentation.
 
-### Roadmap for global documentation
+### Roadmap for high level documentation
 
-This is the initial version of global documentation in EventCatalog.
+This is the initial version of high level documentation in EventCatalog.
 
 We plan to add the following features:
 
 - Add support to embed EventCatalog visualizations into your documentation pages
 - Embed EventCatalog resources into your custom documentation pages
-- Add ability to add runtime blocks into your pages (e.g making requests to get third party data to display)
+- Add ability to add runtime blocks into your pages (e.g making requests to get third party data to display)