@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/dist/docs/development/studio/07-reference.md

@@ -0,0 +1,294 @@
+---
+sidebar_position: 7
+keywords:
+- EventCatalog Studio
+- reference
+sidebar_label: Reference
+title: Studio reference
+description: Configuration, canvas controls, components, connection labels, MCP tools, keyboard shortcuts and limits for EventCatalog Studio.
+---
+
+Everything about Studio and its canvases in one place.
+
+## Configuration {#configuration}
+
+### `studio`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `studio.enabled` | `boolean` | `false` | Turns Studio on in production. Studio is on in `eventcatalog dev` unless this is `false`. `false` turns it off everywhere. |
+
+### `storage`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `storage.type` | `'memory'` \| `'sqlite'` | `'memory'` | `'memory'` keeps canvases while the server runs. `'sqlite'` keeps them in a database file. |
+| `storage.path` | `string` | `'.eventcatalog/eventcatalog.db'` | The SQLite database file, relative to your catalog. |
+
+SQLite storage needs Node.js 22.13 or later.
+
+### Related options
+
+| Option | Why it matters for Studio |
+|---|---|
+| `output` | Must be `'server'` for Studio in production, and for agents to connect through the MCP server. |
+| `auth.enabled` | With [authentication](/docs/development/authentication/introduction) on, only signed-in people can open canvases. |
+| `mcp.enabled` | Agents connect through the MCP server. Setting it to `false` stops agents connecting. |
+| `security.allowedDomains` | Needed when a proxy serves your catalog over HTTPS. |
+
+### When Studio is on
+
+| Command | `studio.enabled` not set | `true` | `false` |
+|---|---|---|---|
+| `eventcatalog dev` | On | On | Off |
+| `eventcatalog start` (`output: 'server'`) | Off | On | Off |
+| Static build (`output: 'static'`) | Off | Off | Off |
+
+### Example
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+  studio: {
+    enabled: true,
+  },
+  storage: {
+    type: 'sqlite',
+    path: '/data/eventcatalog.db',
+  },
+};
+```
+
+See the [full configuration reference](/docs/api/config) for every EventCatalog option.
+
+## Canvas {#canvas}
+
+### Toolbar
+
+| Button | Shortcut | What it does |
+|---|---|---|
+| Lock | | Locks the canvas, so it can be looked at but not changed |
+| Select | <kbd>V</kbd> | Select and move nodes |
+| Hand | <kbd>H</kbd> | Drag to move around |
+| L1 / L2 / L3 | <kbd>1</kbd> <kbd>2</kbd> <kbd>3</kbd> | Change the [level](#levels) |
+| Sticky note | <kbd>N</kbd> | Click where the note goes |
+| Text | <kbd>T</kbd> | Click anywhere and type |
+| Comment | <kbd>C</kbd> | Click a node, or a spot, to comment |
+| Hotspot | <kbd>A</kbd> | Click a node, or a spot, to flag a risk |
+
+The controls at the bottom left zoom, undo and redo, fit the view (<kbd>⇧</kbd> <kbd>1</kbd>), reorder the diagram, and list comments and hotspots.
+
+### Levels
+
+| Level | Shows |
+|---|---|
+| **L1** | Domains, systems and their relationships |
+| **L2** | Services and data stores |
+| **L3** | Everything, including messages and channels |
+
+L1 is unavailable until the canvas has a domain or system.
+
+### Canvas menu
+
+The three dots next to the canvas title.
+
+![The canvas menu](./img/canvas-menu.png)
+
+| Item | Shortcut |
+|---|---|
+| Open… | <kbd>⌘</kbd> <kbd>O</kbd> |
+| Save to file… | <kbd>⌘</kbd> <kbd>S</kbd> |
+| Export image… | <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>E</kbd> |
+| Live collaboration… | |
+| Connect your AI agent… | |
+| Help | <kbd>?</kbd> |
+| Rename canvas | |
+| Copy link | |
+| New canvas | |
+| Delete canvas | |
+
+The bottom of the menu shows the connection status, for example **Connected**.
+
+### Right-click menus
+
+| On | Items |
+|---|---|
+| A node | Add comment, Add hotspot, Add a note, Edit details, Copy, Duplicate, Delete |
+| The canvas | Add comment, Add hotspot, Add a sticky note, Paste here, Reorder diagram |
+
+### Statuses
+
+| Status | Meaning |
+|---|---|
+| **Draft** | Being worked on. Every canvas starts as a draft. |
+| **Proposed** | Ready for review |
+| **Accepted** | The agreed design |
+| **Rejected** | Decided against, kept for the record |
+
+- Each status change can have a note. The status menu shows the history, with who changed it, when and the note.
+- Changing the nodes or connections on an accepted or rejected canvas makes it a draft again.
+
+### Hotspots
+
+| Field | Values |
+|---|---|
+| Severity | **Critical** (red), **Warning** (amber) or **Info** (blue) |
+| Title | Up to 120 characters, for example "Single point of failure" |
+| Description | Optional. Why it matters, and what to do about it |
+
+- A hotspot is on a node, and moves with it, or on a spot on the canvas.
+- The **Hotspots** list shows the most severe first.
+- At L1 and L2, hotspots inside a domain or system are shown on that domain or system.
+
+### Studio page
+
+The Studio page lists canvases with their status, contents, open comments, who created them, and when they were last updated. Filter by name or status. Each canvas's menu has **Make a copy** and **Delete**.
+
+### Limits
+
+| Limit | Value |
+|---|---|
+| Canvas title | 200 characters |
+| Your name | 60 characters |
+| `.eventcatalog` file | 2 MB |
+
+## Components and connections {#components-and-connections}
+
+### Components
+
+New components start at version `0.0.1`.
+
+| Group | Component | Description |
+|---|---|---|
+| Boundaries | Domain | A business area, e.g. Sales |
+| | System | Services doing one job |
+| Services | Service | An API, worker or function |
+| | View | A screen or app people use |
+| | External System | A third party you use |
+| | Agent | An AI agent at work |
+| Messages | Event | Something that happened |
+| | Command | A request to do something |
+| | Query | A request for data |
+| | Channel | A topic, queue or bus |
+| Data | Database | Tables, e.g. PostgreSQL |
+| | Cache | Fast data, e.g. Redis |
+| | Search index | Search, e.g. Elasticsearch |
+| | Object store | Files and blobs, e.g. S3 |
+| | Entity | Part of the domain model |
+| People | Actor | Someone who uses it |
+| | Team | Who owns what |
+
+Sticky notes and text are added from the toolbar.
+
+### Catalog resources
+
+You can add these resources from your catalog: domains, systems, services, events, commands, queries, channels and data stores. They are added at their latest version, with their name, version and summary from your catalog.
+
+### Connection labels
+
+When you connect two nodes, Studio labels the connection with EventCatalog's wording:
+
+| From | To | Label |
+|---|---|---|
+| Service, agent, actor, external system or view | Event | publishes event |
+| Service, agent, actor, external system or view | Command | invokes |
+| Service, agent, actor, external system or view | Query | requests |
+| Event | Anything but a message or channel | subscribed by |
+| Command or query | Anything but a message or channel | accepts |
+| Message | Message | triggers |
+| Message | Channel | sent to |
+| Channel | Anything | routes to |
+| Anything else | Channel | publishes to |
+| Anything | Data store | writes to |
+| Data store | Anything | read by |
+| Actor | Anything | uses |
+| Anything | View | serves |
+| Anything | External system | calls |
+| Anything | Actor | notifies |
+| Team | Anything | owns |
+| Entity | Entity | references |
+| Message | Entity | carries |
+| Anything else | Entity | manages |
+
+Agents can set their own labels through the [MCP tools](#mcp-tools).
+
+## MCP tools {#mcp-tools}
+
+When Studio is on, the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) has these tools for canvases. Unlike the other MCP tools, they change your canvases.
+
+| Tool | What it does |
+|---|---|
+| `openCanvas` | Shows a canvas in the chat, in clients that support MCP Apps |
+| `listCanvases` | Lists canvases and who is on each one |
+| `createCanvas` | Creates a canvas and returns its link |
+| `getCanvas` | Reads a canvas: its nodes, connections, comments and who is on it |
+| `addToCanvas` | Adds catalog resources or new components, and connects them |
+| `updateCanvasNode` | Renames, describes, versions or moves a node |
+| `connectCanvasNodes` | Connects nodes |
+| `removeFromCanvas` | Removes nodes or connections |
+| `layoutCanvas` | Lays out the whole canvas |
+| `setCanvasStatus` | Sets the status to draft, proposed, accepted or rejected, with a note |
+| `commentOnCanvas` | Starts a comment thread on a node or a spot |
+| `replyToCanvasComment` | Replies to a thread |
+| `resolveCanvasComment` | Resolves or reopens a thread |
+
+Every tool takes an optional `agentName`, the name people on the canvas see. It defaults to the name of the client, for example Claude, Claude Code, ChatGPT or Cursor.
+
+### How agents appear
+
+- An agent has its own pointer and name on the canvas.
+- Its changes appear one step at a time, with what it is doing, for example "Connecting InstalmentPlanApproved to Notification Service".
+- A banner shows when an agent is working. Choose **Follow** to move your view with it.
+
+### Browser tools (WebMCP)
+
+When WebMCP is turned on in the **Connect your AI agent** dialog, the open canvas offers agents in the browser these tools: `get_canvas`, `search_catalog`, `add_to_canvas`, `update_node`, `connect_nodes`, `remove_from_canvas`, `layout_canvas`, `set_canvas_status`, `add_comment`, `reply_to_comment`, `resolve_comment` and `show_nodes`.
+
+## Keyboard shortcuts {#keyboard-shortcuts}
+
+Press <kbd>?</kbd> on a canvas to see these shortcuts. On Windows and Linux, use <kbd>Ctrl</kbd> instead of <kbd>⌘</kbd>.
+
+![The keyboard shortcuts dialog](./img/keyboard-shortcuts.png)
+
+### Tools
+
+| Action | Shortcut |
+|---|---|
+| Select | <kbd>V</kbd> |
+| Hand (move around) | <kbd>H</kbd> |
+| Sticky note | <kbd>N</kbd> |
+| Text | <kbd>T</kbd> |
+| Comment | <kbd>C</kbd> |
+| Hotspot | <kbd>A</kbd> |
+| Level 1 / 2 / 3 | <kbd>1</kbd> <kbd>2</kbd> <kbd>3</kbd> |
+| Back to selecting | <kbd>Esc</kbd> |
+
+### Canvas
+
+| Action | Shortcut |
+|---|---|
+| Select everything | <kbd>⌘</kbd> <kbd>A</kbd> |
+| Select several | <kbd>⇧</kbd> + click |
+| Delete what's selected | <kbd>Delete</kbd> |
+| Duplicate | <kbd>⌘</kbd> <kbd>D</kbd> |
+| Copy / paste | <kbd>⌘</kbd> <kbd>C</kbd> / <kbd>⌘</kbd> <kbd>V</kbd> |
+| Undo / redo | <kbd>⌘</kbd> <kbd>Z</kbd> / <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>Z</kbd> |
+| Move around | Scroll |
+| Zoom | <kbd>⌘</kbd> + scroll |
+| Fit view | <kbd>⇧</kbd> <kbd>1</kbd> |
+
+### Notes and text
+
+| Action | Shortcut |
+|---|---|
+| Write on one | Double-click |
+| Finish writing | <kbd>Esc</kbd> |
+
+### Files
+
+| Action | Shortcut |
+|---|---|
+| Open a file | <kbd>⌘</kbd> <kbd>O</kbd> |
+| Save to file | <kbd>⌘</kbd> <kbd>S</kbd> |
+| Export image | <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>E</kbd> |
+| Help | <kbd>?</kbd> |

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

@@ -0,0 +1,12 @@
+{
+  "label": "Studio",
+  "position": 4.5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/studio",
+    "title": "EventCatalog Studio",
+    "description": "Design changes to your architecture on live canvases, with your team and AI agents."
+  }
+}

package/dist/docs/development/upgrading/v5.md

@@ -0,0 +1,345 @@
+---
+sidebar_position: 1.5
+keywords:
+- Upgrade EventCatalog
+- EventCatalog v5
+sidebar_label: v5
+title: Upgrade to EventCatalog v5
+description: How to upgrade to EventCatalog v5.
+---
+
+This guide will help you upgrade from v4 to v5 of EventCatalog. (Missed the announcement? [Read the blog post](/blog/eventcatalog-v5) to find out what's changing.)
+
+EventCatalog v5 includes every feature in one product, moves the core to the Business Source License 1.1, and brings new visualiser diagrams with levels, flow grouping, Resources pages for more resources, and interactive diagrams in MCP clients.
+
+## Upgrade EventCatalog
+
+:::warning Install v5 from a clean install
+v5 uses React 19. If you upgrade over an existing v4 install, your package manager can keep React 18 at the top of `node_modules` and give `@eventcatalog/core` its own copy of React 19. The build then fails with errors such as `Cannot read properties of null (reading 'useState')`.
+
+Delete your installed packages and lock file before you install v5.
+:::
+
+1. Create a branch for the upgrade.
+1. Delete `node_modules`, `.astro` and `.eventcatalog-core` (if you have one).
+1. Delete your lock file: `package-lock.json`, `yarn.lock` or `pnpm-lock.yaml`.
+1. If your `package.json` lists `react` or `react-dom`, change them to `^19.2.0`.
+1. Install v5:
+
+```bash
+rm -rf node_modules .astro .eventcatalog-core package-lock.json
+npm install @eventcatalog/core@latest
+```
+
+If you use yarn or pnpm, delete `yarn.lock` or `pnpm-lock.yaml` instead of `package-lock.json`, and install with that package manager.
+
+_Problems upgrading? [Try resetting your project](/docs/development/upgrading#having-problems)._
+
+## After you upgrade
+
+Most v4 catalogs build on v5 without changes to their resources. The changes most likely to affect you are flow step validation, `pages/api` routes in static builds, custom React components, and links to visualiser pages.
+
+1. Run `eventcatalog build` and fix any flow step errors it reports.
+1. Run your catalog locally and check custom pages, custom components, custom navigation, and links to visualiser pages.
+
+### The license has changed
+
+`@eventcatalog/core` 5.0.0 and later is licensed under the Business Source License 1.1 (`BUSL-1.1`). Releases up to and including 4.x stay under the MIT License. Ecosystem packages, such as `@eventcatalog/create-eventcatalog`, stay MIT. The generators, integrations and plugins we publish are MIT too, and no longer need a license key. You can remove `EVENTCATALOG_LICENSE_KEY_*` variables and `licenseKey` options; they are ignored.
+
+Read the [licensing FAQ](/license-faq) to find out whether you need a commercial license, and [pricing](/pricing) for prices. The [blog post](/blog/eventcatalog-v5) explains why the license changed.
+
+If you have a license, add your `license.jwt` file to the catalog. See [License file](/docs/development/license/license-file).
+
+### Every feature is included
+
+Every feature now works without `EVENTCATALOG_SCALE_LICENSE_KEY`, a Starter or Scale plan, or a Backstage license key. This includes custom documentation, resource docs, custom pages, custom styles, the schema API and `schemas.txt`, Fields Explorer lineage, schema diffs, schema and directory sources, private remote files, analytics integrations, embedding, federation, the assistant, the MCP server, authentication and governance checks.
+
+Federation is free for organizations that qualify for Free Use. Commercial customers need the Enterprise plan to use federation in production.
+
+The [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant), the [MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) and [authentication](/docs/development/authentication/introduction) still need server output (`output: 'server'`) and their configuration files.
+
+#### What do I need to do?
+
+Nothing. You can remove `EVENTCATALOG_SCALE_LICENSE_KEY` and `EVENTCATALOG_STARTER_LICENSE_KEY` from your environment once you have a `license.jwt`. If you keep them, EventCatalog still recognizes them.
+
+## Removed
+
+The following features have now been entirely removed from the code base and can no longer be used.
+
+### Removed: Billing settings page
+
+The billing settings page (`/settings/billing`) and the upgrade prompts are removed. Your license is shown on the new **Settings > License** page.
+
+#### What do I need to do?
+
+Update any links to `/settings/billing` to `/settings/license`.
+
+### Removed: Domain Integration Map
+
+The Domain Integration Map page (`/visualiser/domain-integrations`) is removed. Level 1 of a domain's Diagram shows how domains integrate.
+
+#### What do I need to do?
+
+Update any custom navigation or links that point to `/visualiser/domain-integrations`.
+
+### Removed: Data Dependency Graph
+
+The service Data Dependency Graph (`/visualiser/services/:id/:version/data`) is removed, along with its sidebar link. Level 2 of the service's Diagram shows the same data stores and the services it talks to. The old route redirects there.
+
+#### What do I need to do?
+
+Nothing. Links redirect. If you embed this page, see [Changed: visualiser routes and levels](#changed-visualiser-routes-and-levels).
+
+### Removed: Separate Resource, Context and System Diagram pages
+
+Domains and systems now have a single **Diagram** page with three levels. The domain System Diagram (`/visualiser/domains/:id/:version/systems-context`) and the system Context Diagram (`/visualiser/systems/:id/:version/context`) redirect to level 1 of the Diagram page. The old Resource Diagram pages are replaced by the Diagram page.
+
+#### What do I need to do?
+
+Nothing. Links redirect. See [Changed: visualiser routes and levels](#changed-visualiser-routes-and-levels).
+
+### Removed: Architecture overview pages
+
+The architecture overview pages (`/architecture/{type}/{id}/{version}`) for domains, systems and services are replaced by their Resources pages. Old links redirect to the Resources page, or to the docs page when there is nothing to list. The sidebar's Architecture section no longer has an **Overview** link.
+
+#### What do I need to do?
+
+Nothing. Links redirect. Update custom navigation to point to `/docs/{type}/{id}/{version}/resources`.
+
+### Removed: "Open in EventCatalog Studio" menu item
+
+The visualiser canvas menu no longer has the **Open in EventCatalog Studio** item.
+
+#### What do I need to do?
+
+Remove any internal guidance that tells people to use this menu item.
+
+### Removed: `EVENTCATALOG_SHOW_BRANDING`
+
+The EventCatalog branding (the Discord and GitHub links in the header and the footer) is always shown. `EVENTCATALOG_SHOW_BRANDING` is no longer used.
+
+#### What do I need to do?
+
+Remove `EVENTCATALOG_SHOW_BRANDING` from your environment.
+
+### Removed: `ENABLE_EMBED`
+
+In v4, the EventCatalog CLI set `ENABLE_EMBED` from your license. `ENABLE_EMBED`, `EVENTCATALOG_STARTER` and `EVENTCATALOG_SCALE` are no longer passed to the Astro runtime. Embedding works for every catalog: add `embed=true` to a URL. See [Embed EventCatalog](/docs/development/customization/embed-eventcatalog).
+
+#### What do I need to do?
+
+Nothing, unless your custom code uses them. If it reads `ENABLE_EMBED`, `EVENTCATALOG_STARTER` or `EVENTCATALOG_SCALE`, or imports `isEventCatalogStarterEnabled` or `isEventCatalogScaleEnabled` from `@utils/feature`, remove those checks.
+
+## Breaking changes
+
+The following changes are considered breaking changes in EventCatalog v5. Breaking changes may or may not affect your catalog depending on how much you customize EventCatalog.
+
+### Changed: visualiser routes and levels
+
+Every diagram now has the same three levels, shown as L1, L2 and L3 in the canvas toolbar:
+
+| Level | `?level=` | Shows |
+| --- | --- | --- |
+| L1 | `1` | Domains, systems and their relationships |
+| L2 | `2` | Services and data stores |
+| L3 | `3` | Adds messages and channels |
+
+Domain and system diagrams live at `/visualiser/domains/:id/:version` and `/visualiser/systems/:id/:version`. Old routes redirect:
+
+| Old route | Redirects to |
+| --- | --- |
+| `/visualiser/domains/:id/:version/systems-context` | `/visualiser/domains/:id/:version?level=1` |
+| `/visualiser/systems/:id/:version/context` | `/visualiser/systems/:id/:version?level=1` |
+| `/visualiser/services/:id/:version/data` | `/visualiser/services/:id/:version?level=2` |
+
+#### What do I need to do?
+
+- If you link to a diagram with `?level=`, check the value matches the new levels.
+- Update embedded URLs that use the old routes. The redirect drops the query string, including `embed=true`.
+- Update custom navigation that points to the old routes.
+
+### Changed: sidebar labels
+
+Sidebar links have been renamed:
+
+| v4 label | v5 label |
+| --- | --- |
+| System Diagram (domains) | Diagram |
+| Resource Diagram (domains and systems) | Diagram |
+| Context Diagram (systems) | Diagram |
+| Map | Diagram |
+| Entity Map | Entity Diagram |
+| System Context Map | System Context Diagram |
+| Domain Resources | Resources |
+| System Resources | Resources |
+| Data Dependency Graph | Removed |
+| Overview (in the Architecture section) | Removed |
+
+Entity diagram pages and custom docs domain embeds also say "Diagram" instead of "Map".
+
+#### What do I need to do?
+
+Update screenshots, onboarding docs and training material that use the old labels.
+
+### Changed: saved layouts for old Resource Diagrams don't carry over
+
+Diagrams are now laid out with ELK instead of dagre, and domains and systems are laid out inside their boxes. Layouts you saved in dev mode for a domain's or system's old Resource Diagram don't carry over to the new Diagram page. Layouts saved for a system's context diagram carry over to level 1.
+
+#### What do I need to do?
+
+Open the diagram in `eventcatalog dev` and save the layout again if needed.
+
+### Changed: `pages/api` routes require `output: 'server'`
+
+Custom pages are now served for every catalog. In v4, catalogs without a Scale license skipped them. A `pages/api` directory now requires server output: a static build fails with a message instead of skipping the routes.
+
+#### What do I need to do?
+
+If you have a `pages/api` directory, set `output: 'server'` in `eventcatalog.config.js`, or remove the directory.
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+See the [custom pages and API routes reference](/docs/development/customization/custom-pages-and-api-routes/reference).
+
+### Changed: custom React components run on React 19
+
+EventCatalog now uses React and React DOM 19. React components in your catalog's `components/` folder run on React 19.
+
+#### What do I need to do?
+
+If your `package.json` lists `react` or `react-dom`, change them to `^19.2.0` and reinstall from a clean install, as in [Upgrade EventCatalog](#upgrade-eventcatalog).
+
+If any of your components use APIs that React 19 removed, update them:
+
+- `defaultProps` on function components
+- `propTypes`
+- string refs
+- `ReactDOM.render`
+- `findDOMNode`
+
+See the [custom components reference](/docs/development/components/custom-components/reference#react-components).
+
+### Changed: header shows `repositoryUrl` next to the EventCatalog links
+
+When [`repositoryUrl`](/docs/api/config#repositoryUrl) is set, the header shows your repository link next to the EventCatalog Discord and GitHub links, rather than in place of them.
+
+#### What do I need to do?
+
+Nothing.
+
+### Changed: flow steps are validated
+
+Mistakes in flows no longer fail silently:
+
+- Unknown step properties fail the build. Custom properties must start with `x-`.
+- Steps that use two node types, or both `next_step` and `next_steps`, fail with a message naming the step and what to change.
+- A `next_step` to a step that doesn't exist, or a reference to a resource that isn't in the catalog, logs a warning naming the flow and the step.
+- The step `type` field is still accepted, but ignored.
+
+The [EventCatalog Linter](/docs/development/developer-tools/eventcatalog-linter) checks the same rules, and adds `refs/flow-step-exists` for next steps that aren't in the flow.
+
+#### What do I need to do?
+
+Run `eventcatalog build` and fix any errors. Rename custom step properties to start with `x-`:
+
+```diff title="flows/Checkout/index.mdx"
+steps:
+  - id: place-order
+    title: Place order
+    service:
+      id: OrderService
+-   priority: high
++   x-priority: high
+```
+
+### Changed: `@eventcatalog/visualiser` API
+
+This only affects you if you use the `@eventcatalog/visualiser` package directly, for example to embed the visualiser in your own application.
+
+- `layoutGraph` now returns a promise.
+- The dagre helpers (`createDagreGraph`, `layoutDagreGraph`, `getNodesAndEdgesFromDagre`, `calculatedNodes`) are removed.
+- Edges are drawn along the route in `data.route` when there is one.
+- A new `@eventcatalog/visualiser/layout` entry (no React) exports `layoutWithElk`, `getNodeSize`, `hideMessageNodes`, `hideNodes`, `getMessagesLabel`, `isCarrier` and `isMessageNode`.
+
+#### What do I need to do?
+
+`await` calls to `layoutGraph`, and replace the dagre helpers with `layoutWithElk` from `@eventcatalog/visualiser/layout`.
+
+## New features
+
+The following new features and improvements have been added to EventCatalog v5.
+
+### Diagram levels and the canvas toolbar
+
+Every diagram has a floating canvas toolbar with the levels (L1, L2, L3), simulate messages, the minimap and fit to view. Levels a diagram doesn't have are greyed out. The level is kept in the URL, so shared links open at the same level.
+
+Clicking a legend entry now hides or shows those nodes. The canvas menu has a **Hide messages** option.
+
+### Domain and system Diagram pages
+
+A domain's Diagram shows the domain with its systems and the other domains they send messages to or receive them from (L1). L2 expands the systems into their services and data stores, and L3 adds messages and channels. Subdomains are shown as domains inside the domain.
+
+![Payments domain diagram at level 1](./img/domain-diagram-l1.png)
+
+![Payments domain diagram at level 2](./img/domain-diagram-l2.png)
+
+On a domain's diagram, the toolbar has **Highlight cross-domain communication**, which picks out the edges to and from other domains.
+
+A system's Diagram shows the system context at L1, expands the system into its services at L2, and adds messages and channels at L3. Read more in [System diagrams](/docs/development/guides/systems/system-context-maps).
+
+### Group flows by domain, system or team
+
+Flows can group their steps by domain, system, team, or domain then system, drawn as boxes or lanes. Use the **Group by** menu (top right, or press G). Groups come from the catalog, so your flows need no changes. The choice is kept in the URL (`?group=system&groupStyle=boxes`).
+
+![Flow grouped by system with the Group by menu open](./img/flow-group-by.png)
+
+To start a flow grouped in your docs, use `<Flow lanes="team" />`. See the [Flow component](/docs/development/components/components/flow).
+
+Flows no longer show the L1/L2/L3 levels. The step-by-step walkthrough is smaller and starts at the first step: it numbers the steps walked so far, rings the current step, and offers a dropdown at branches.
+
+### Channel flow steps
+
+Flow steps can reference channels with `channel: { id, version }`. A step's `title` is now optional and defaults to the name of what it references. The SDK adds `FlowBuilder.addChannelStep`.
+
+```md title="flows/Checkout/index.mdx"
+steps:
+  - id: orders-topic
+    channel:
+      id: orders
+      version: 1.0.0
+    next_step: notify-customer
+```
+
+Read more in the [flows documentation](/docs/development/guides/resources/flows/introduction).
+
+### Resources pages for services, flows, channels and messages
+
+Services, flows, channels, events, commands and queries now have a Resources page, like domains and systems, linked from Quick Reference in the sidebar. Every Resources page lists the decision records (ADRs) that apply to it, and has a Relationship column (for example Sends, Receives, Reads from, Writes to) with Inbound and Outbound filters.
+
+![Order Service Resources page with Inbound and Outbound filters](./img/service-resources-page.png)
+
+Read more about the [service Resources page](/docs/development/guides/resources/services/resources-page), the [message Resources page](/docs/development/guides/resources/messages/what-are-messages#resources-page) and the [channel Resources page](/docs/development/guides/resources/messages/message-channels/introduction#resources-page).
+
+### Interactive diagrams and schemas in MCP clients
+
+The MCP server has a new `showResource` tool. With `view: "architecture"` it returns a resource's diagram, built the same way as its Diagram page. With `view: "schema"` it shows a message's schema. In MCP clients that support MCP Apps (for example Claude, ChatGPT and VS Code) these open as interactive views. Other clients get Mermaid or the schema code.
+
+Every MCP tool now has a title and is read-only, versions are optional, and hidden resources are not listed. Read more in [interactive diagrams and schemas](/docs/development/ask-your-architecture/mcp-server/getting-started#interactive-diagrams-and-schemas).
+
+### Settings > MCP lists domain MCP servers
+
+**Settings > MCP** lists each domain's MCP server next to the Catalog MCP Server, with full URLs to copy. See the [MCP server documentation](/docs/development/ask-your-architecture/mcp-server/introduction).
+
+### License status in the CLI and Settings > License
+
+`eventcatalog dev` and `eventcatalog build` show the catalog's license or trial in the terminal. While you run `eventcatalog dev`, the header shows the trial, or a reminder when your license is about to expire. The new **Settings > License** page shows who the catalog is licensed to and when the license expires.
+
+Read more in [License file](/docs/development/license/license-file).
+
+## Known issues
+
+Please check [EventCatalog issues on GitHub](https://github.com/event-catalog/eventcatalog/issues) for any reported issues, or to file an issue yourself.

package/dist/docs/federation/00-overview.md

@@ -5,10 +5,6 @@ title: EventCatalog Federation
 description: Combine independently owned EventCatalogs into one validated organization-wide catalog.
 ---
 
-import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
-
-<EventCatalogEnterprise />
-
 EventCatalog Federation is a solution for distributed documentation across your organization. Teams document and own their services, domains, messages, ADRs, specifications, schemas, diagrams, and everything else EventCatalog supports in their own catalogs, while Federation combines them into one organization-wide view.
 
 Each team keeps its documentation, ownership, and review workflow in its own EventCatalog project. A central catalog selects those catalogs, validates them together, and materializes their resources as one connected catalog.
@@ -128,11 +124,9 @@ npm run build
 
 `eventcatalog federate` fetches, validates, and materializes the configured sources. `npm run build` renders the resulting catalog. Federation does not run automatically before `dev`, `build`, or `generate`.
 
-:::info Enterprise feature
-
-EventCatalog Federation requires an EventCatalog Enterprise offline license. To try it, email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) and we will send you an offline trial key. Save the `license.jwt` file in the root of your central catalog before running Federation.
+:::info License
 
-Learn more about [offline license validation](/docs/development/license-keys/license-validation#offline-validation).
+Federation is free for organizations that [qualify for Free Use](/license-faq), using their free license key. Commercial customers need the [Enterprise plan](/pricing). Every organization can try it during its 60-day evaluation.
 
 :::