@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/dist/docs/development/license-keys/integrations.md

@@ -7,46 +7,16 @@ keywords:
 - openapi
 - asyncapi
 sidebar_label: Integrations
-title: Getting a license key for integrations
-description: How to use EventCatalog Scale with integrations such as OpenAPI, AsyncAPI, Backstage, and more.
+title: License keys for integrations
+description: From EventCatalog v5, the generators, integrations and plugins EventCatalog publishes are open source under the MIT License and don't need a license key.
 ---
 
-EventCatalog integrations (sometimes called plugins) let you generate your catalog from sources you already have — OpenAPI specs, AsyncAPI documents, Backstage, federated catalogs, and more. You can see the full list on the [integrations page](/integrations).
+From EventCatalog v5, the generators, integrations and plugins EventCatalog publishes are open source under the MIT License and don't need a license key. You can see the full list on the [integrations page](/integrations).
 
-Official integrations are included with EventCatalog Scale. Start Scale from your [EventCatalog Cloud dashboard](https://eventcatalog.cloud/dashboard) and use your Scale license key to unlock supported integrations in your catalog.
+If your config still sets the `licenseKey` option or an `EVENTCATALOG_LICENSE_KEY_*` environment variable, you can remove it. It's ignored.
 
-![Pick your integrations in EventCatalog Cloud](./images/pick-your-integraions.png)
+EventCatalog core is licensed separately. To check whether your organization needs a commercial license, see the [licensing FAQ](/license-faq) and [pricing](/pricing).
 
-Once Scale is active, your license key appears on your [API keys page](https://eventcatalog.cloud/dashboard/api-keys):
-
-![Your license keys in the EventCatalog Cloud API keys dashboard](./images/api-keys-dashboard.png)
-
-## Adding your Scale key to your catalog
-
-Copy your Scale license key from your dashboard into your `.env` file:
-
-```bash title=".env"
-EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key-here
-```
-
-Then configure the integration in your `eventcatalog.config.js` as described in the [integration's documentation](/integrations).
-
-:::info Using plugin API keys?
-If you already have older plugin-specific API keys, you can still use them with the environment variables shown in each integration's documentation.
-
-For example, the OpenAPI plugin supports:
-
-```bash title=".env"
-EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key-here
-```
-
-For new projects, use `EVENTCATALOG_SCALE_LICENSE_KEY`.
+:::info EventCatalog v4 and earlier
+In v4 and earlier, integrations were unlocked with an EventCatalog Scale license key. See the [License Keys overview](/docs/development/license-keys/overview) and [Scale plan](/docs/development/license-keys/plans) pages for how v4 license keys worked.
 :::
-
-## Trying multiple integrations
-
-Scale includes all official integrations, so you can configure multiple integrations in the same catalog with the same Scale license key.
-
-## Need more time?
-
-If 30 days isn't enough to evaluate Scale and integrations in your environment, email us at `hello@eventcatalog.dev` and we'll extend your trial.

package/dist/docs/development/license-keys/license-validation.md

@@ -9,6 +9,10 @@ title: How license validation works
 description: How EventCatalog validates your license keys online and offline.
 ---
 
+:::info EventCatalog v4 and earlier
+This page covers license keys for **EventCatalog v4 and earlier**. From v5, every feature and integration is included in one product. See the [licensing FAQ](/license-faq) and [pricing](/pricing).
+:::
+
 EventCatalog validates commercial features using online license keys or offline license files. Scale and integration keys use online validation by default. Enterprise features, including Federation, require an offline license file.
 
 ## Online validation (default)

package/dist/docs/development/license-keys/overview.md

@@ -9,7 +9,11 @@ title: License Keys Overview
 description: Learn how license keys work in EventCatalog, how to get a free trial, and where to find your keys.
 ---
 
-EventCatalog is open source with a [community edition and commercial plans](/pricing). EventCatalog Scale, Enterprise, and commercial integrations are unlocked using **license keys**.
+:::info EventCatalog v4 and earlier
+This page covers license keys for **EventCatalog v4 and earlier**. From v5, every feature and integration is included in one product. See the [licensing FAQ](/license-faq) and [pricing](/pricing).
+:::
+
+EventCatalog v4 has a community edition and commercial plans. EventCatalog Scale, Enterprise, and commercial integrations are unlocked using **license keys**.
 
 If you are using the community edition, you don't need a license key and can skip this section.
 

package/dist/docs/development/license-keys/plans.md

@@ -9,9 +9,11 @@ title: Getting a license key for EventCatalog Scale
 description: How to start an EventCatalog Scale plan in EventCatalog Cloud and get your license key.
 ---
 
-EventCatalog Scale is the self-serve commercial plan for teams that need automation, integrations, governance, and a living architecture catalog that stays in sync with code, specs, teams, and tools.
+:::info EventCatalog v4 and earlier
+This page covers license keys for **EventCatalog v4 and earlier**. From v5, every feature and integration is included in one product. See the [licensing FAQ](/license-faq) and [pricing](/pricing).
+:::
 
-See the [pricing page](/pricing) for a full breakdown of what Scale includes.
+EventCatalog Scale is the self-serve commercial plan for teams that need automation, integrations, governance, and a living architecture catalog that stays in sync with code, specs, teams, and tools.
 
 ## Starting a plan
 

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

@@ -0,0 +1,60 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Studio
+- architecture design
+- collaborative canvas
+sidebar_label: What is Studio?
+title: What is EventCatalog Studio?
+description: Design changes to your architecture on live canvases, with your team and AI agents.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.0.0" />
+
+EventCatalog Studio lets your teams design changes to their architecture on live canvases, inside your catalog.
+
+Your catalog documents how your architecture works today. Studio is where you plan what comes next: a new service, a new event, a different way to split a domain. You start from the resources you already document, add the parts that don't exist yet, and work on it together with your team and your AI agents.
+
+Studio is experimental while we shape it with your feedback. Tell us what you think in [Discord](https://eventcatalog.dev/discord) or on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
+
+![A Studio canvas with two people and Claude working on it together](./img/studio-collaboration.png)
+
+## Why use Studio?
+
+Planning conversations often happen outside the catalog, on whiteboards, slides or diagram tools that know nothing about your architecture. Someone redraws the services by hand, and the diagram is out of date before the meeting ends.
+
+With Studio:
+
+- **You start from real resources.** Drag your domains, systems, services, messages, channels and data stores onto a canvas, with their real names, versions and summaries.
+- **You sketch what's new next to what exists.** Add proposed services, messages and data stores, and connect them to the resources they change.
+- **Team collaboration.** Everyone on a canvas sees each other's pointers and edits, and can comment and flag risks.
+- **You record the decision.** Mark a canvas as proposed, accepted or rejected, with a note, so you can see later what was decided and why.
+- **AI agents work with you.** Agents connect through the [MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) and edit the same canvas, using the resources in your catalog.
+
+:::info Studio doesn't change your catalog
+A canvas is a design, kept separately from your catalog files. Adding, editing or deleting anything on a canvas never changes your documentation.
+
+When a design is built, your teams document the changes in the catalog as usual.
+:::
+
+## How it works
+
+- Open **Studio** from the sidebar of your catalog. It lists every canvas, with its status and open comments.
+- Each canvas has the same three levels as the diagrams in your catalog: **L1** for domains and systems, **L2** for services and data stores, **L3** for everything, including messages and channels.
+- Canvases are saved by your EventCatalog, in [storage you configure](/docs/development/studio/set-up-persistent-storage). Nothing is sent to a third party.
+
+![The Studio page listing canvases with their status, contents and comments](./img/studio-list.png)
+
+Studio is on when you run `eventcatalog dev`. To use it in a deployed catalog, see [Run Studio in production](/docs/development/studio/run-studio-in-production).
+
+:::tip No catalog yet?
+Try [EventCatalog Studio on the web](https://www.eventcatalog.studio/). It runs in your browser with no sign-up, keeps your design in your browser, and lets you export it to EventCatalog when you're ready.
+:::
+
+## Next steps
+
+- [Create a canvas](/docs/development/studio/create-a-canvas)
+- [Collaborate on a canvas](/docs/development/studio/collaborate-on-a-canvas)
+- [Connect your agent to a canvas](/docs/development/studio/connect-your-agent)

package/dist/docs/development/studio/02-create-a-canvas.md

@@ -0,0 +1,103 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Studio
+- canvas
+sidebar_label: Create a canvas
+title: Create a canvas
+description: Start a canvas, add resources from your catalog, sketch new components and connect them.
+---
+
+A canvas is where you design a change. Give each canvas one topic, such as "Email customers when their review is published" or "Split the Order Service".
+
+This page uses the example catalog from `create-eventcatalog`. Follow along with your own resources, or create the example catalog:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog
+cd my-catalog
+npm run dev
+```
+
+## Start a canvas
+
+1. Open **Studio** from the sidebar, or go to `/studio` in your catalog.
+2. The first time, Studio asks what to call you. Your name is shown next to your pointer and your comments.
+3. Choose **New canvas**, name it for what you're designing, and choose **Create canvas**.
+
+### Start from a diagram
+
+You can also start from any diagram in your catalog. Open the diagram's menu, choose **Open in Studio** and name the canvas.
+
+![The Open in Studio dialog on the Payments domain diagram](./img/open-in-studio.png)
+
+The canvas starts with the diagram's resources, their positions, their domains and systems, and their connections. Change it as you like. Your catalog doesn't change.
+
+## Add resources from your catalog
+
+1. In the palette, choose **Catalog Resources**.
+2. Search for a resource, for example `moderation`.
+3. Click it to add it, or drag it onto the canvas.
+
+When you add a service or a message, choose what comes with it:
+
+- **Just the service**: the resource on its own, connected to what is already on the canvas.
+- **With its connections**: the resource and what it sends, receives and stores. Tick the groups you want.
+
+For example, adding the **Review Moderation Worker** with only **Messages it sends** ticked adds the service and the two events it publishes, already connected:
+
+![The Review Moderation Worker and the two events it publishes](./img/add-service-with-connections.png)
+
+Catalog resources keep the name, version and summary from your catalog. To change them, change them in your catalog.
+
+## Add something new
+
+Use the **Components** tab for things that don't exist yet, such as a proposed service, event or database.
+
+1. In the palette, choose **Components**.
+2. Click a component to add it, or drag it onto the canvas. New components start at version `0.0.1`.
+3. Double-click it to set its name, version and summary. Changes save as you type.
+
+![The Components tab next to a canvas](./img/components.png)
+
+See the [reference](/docs/development/studio/reference#components) for every component.
+
+## Connect nodes
+
+Drag from the dot on the edge of one node to the dot on another. Studio labels the connection with EventCatalog's wording.
+
+For example, connecting the **Review Published** event to a new **Review Emails** service is labelled **subscribed by**:
+
+![A new Review Emails service subscribed to the Review Published event](./img/new-service-connected.png)
+
+To put a node inside a domain or system, drag it onto the box and drop it when it highlights.
+
+To tidy the whole canvas, choose **Reorder diagram** in the toolbar at the bottom.
+
+## Edit a node
+
+Double-click a node, or right-click it and choose **Edit details**. The panel shows its name, version and summary, and what it connects to.
+
+![The details panel for a service](./img/node-details.png)
+
+Right-click a node to comment on it, flag a hotspot, add a note, copy, duplicate or delete it.
+
+## Change the level
+
+Choose **L1**, **L2** or **L3** in the toolbar, or press <kbd>1</kbd>, <kbd>2</kbd> or <kbd>3</kbd>.
+
+| Level | Shows |
+|---|---|
+| **L1** | Domains, systems and their relationships |
+| **L2** | Services and data stores |
+| **L3** | Everything, including messages and channels |
+
+You draw at L3. L1 and L2 summarise it: at L2, messages fold into the connections between services, and at L1, services fold into their systems. Use L1 or L2 when you want to talk about the big picture, without every message.
+
+![The same design at L2, with the event folded into the connection](./img/canvas-level-2.png)
+
+L1 is greyed out until the canvas has a domain or system.
+
+## Next steps
+
+- [Collaborate on a canvas](/docs/development/studio/collaborate-on-a-canvas) with your team.
+- [Connect your agent to a canvas](/docs/development/studio/connect-your-agent).

package/dist/docs/development/studio/03-set-up-persistent-storage.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Studio
+- storage
+- sqlite
+sidebar_label: Set up persistent storage
+title: Set up persistent storage
+description: Save canvases to a SQLite database so they survive restarts and redeploys.
+---
+
+By default, canvases are kept in memory and are lost when the server restarts. To keep them, save them to a SQLite database file.
+
+You need **Node.js 22.13 or later**.
+
+## Save canvases to SQLite
+
+1. In `eventcatalog.config.js`, set `storage`:
+
+   ```js title="eventcatalog.config.js"
+   export default {
+     storage: {
+       type: 'sqlite',
+       path: '.eventcatalog/eventcatalog.db',
+     },
+   };
+   ```
+
+   The path is relative to your catalog. If you leave it out, it defaults to `.eventcatalog/eventcatalog.db`.
+
+2. Restart `eventcatalog dev` or `eventcatalog start`. EventCatalog creates the database, and keeps it up to date each time it starts.
+
+3. Open **Studio**. The bottom of the list shows where canvases are saved, for example **Saved in .eventcatalog/eventcatalog.db**.
+
+## In a container
+
+Put the database on a volume, so it survives redeploys:
+
+```js title="eventcatalog.config.js"
+export default {
+  storage: {
+    type: 'sqlite',
+    path: '/data/eventcatalog.db',
+  },
+};
+```
+
+Mount a volume at `/data` when you run the container.
+
+## How canvases are saved
+
+Canvases save automatically as people work. The server keeps a working copy of each canvas in memory, and writes it to the database a moment after each change and when the server stops, so storage never slows the canvas down.
+
+Canvases stay in your infrastructure. Nothing is sent to a third party.
+
+| 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 database file, relative to your catalog. |

package/dist/docs/development/studio/04-collaborate-on-a-canvas.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog Studio
+- collaboration
+- comments
+- hotspots
+sidebar_label: Collaborate on a canvas
+title: Collaborate on a canvas
+description: Share a canvas, work on it live, discuss it, and record the decision.
+---
+
+## Share a canvas
+
+1. On the canvas, choose **Share**.
+2. Choose **Copy link**, or **Invite people** to email an invite or copy an invite message.
+
+![The Share dialog](./img/share.png)
+
+Anyone with the link opens the canvas in your catalog and edits it with you.
+
+When [authentication](/docs/development/authentication/introduction) is on, only signed-in people can open canvases, and they appear with the name and picture they signed in with. Without authentication, Studio asks each person for a name, and keeps it in their browser.
+
+## Work on it live
+
+Everyone on a canvas sees each other's pointers, names and changes as they happen. Changes save automatically.
+
+- The avatars at the top right show who is on the canvas. Click one to jump to what that person is looking at.
+- Click your own avatar to change your name and colour.
+
+## Comment
+
+1. Choose **Comment** in the toolbar, or press <kbd>C</kbd>.
+2. Click a node, or a spot on the canvas.
+3. Type your comment and press <kbd>Enter</kbd>.
+
+Click a comment pin to reply. Choose **Resolve** when the thread is settled. **Comments** at the bottom of the canvas lists every thread.
+
+![A comment thread on the Pay Later Provider](./img/comments.png)
+
+## Flag a risk with a hotspot
+
+A hotspot flags a risk on a node or a spot, such as a single point of failure or data that needs a review.
+
+1. Choose **Hotspot** in the toolbar, or press <kbd>A</kbd>.
+2. Click the node at risk.
+3. Pick **Critical**, **Warning** or **Info**, and add a short title and, if you want, why it matters.
+
+**Hotspots** at the bottom of the canvas lists every hotspot. At L1 and L2, hotspots inside a domain or system are shown on that domain or system, so zooming out never hides a risk.
+
+![A warning hotspot on the Instalment Plans database](./img/hotspots.png)
+
+## Add notes and text
+
+- **Sticky note** (<kbd>N</kbd>): click where it goes and type. Use notes for assumptions, scope and open questions.
+- **Text** (<kbd>T</kbd>): click anywhere and type. Use text for headings and labels.
+
+Double-click a note or text to edit it.
+
+## Record the decision
+
+Every canvas has a status: **Draft**, **Proposed**, **Accepted** or **Rejected**.
+
+1. Choose the status next to the canvas title.
+2. Add a note if you want, for example `Agreed in the architecture review`.
+3. Pick the new status.
+
+The menu shows the history of status changes, with who made each change, when, and the note.
+
+![The status menu with a note](./img/status.png)
+
+Changing the nodes or connections on an accepted or rejected canvas makes it a draft again, so a decision always matches the design it was made on.
+
+To find designs waiting for review, open **Studio** and filter by **Proposed**.
+
+## Lock the canvas
+
+Choose the lock in the toolbar. Everyone can still look at the canvas, but no one can change it until it is unlocked.

package/dist/docs/development/studio/05-connect-your-agent.md

@@ -0,0 +1,102 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog Studio
+- AI agents
+- MCP
+- MCP Apps
+sidebar_label: Connect your agent to a canvas
+title: Connect your agent to a canvas
+description: Bring Claude, ChatGPT, Cursor or another AI agent onto a canvas to design with you.
+---
+
+AI agents can join a canvas and work on it with you, live. An agent can add resources from your catalog, sketch new components, connect them, tidy the layout, comment and change the status.
+
+Agents join like a person does. Each one has its own pointer and name, and you see what it's doing ("Connecting InstalmentPlanApproved to Notification Service") as it works. Choose **Follow** on the "is working" banner to move your view with it.
+
+![Claude connecting an event to the Notification Service while two people are on the canvas](./img/studio-collaboration.png)
+
+## Before you start
+
+Agents connect through the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction), so your catalog must run with `output: 'server'`, including when you use `eventcatalog dev`.
+
+The MCP server is at `/docs/mcp`, for example `https://your-eventcatalog.com/docs/mcp`.
+
+## Connect with one prompt
+
+1. On the canvas, choose **Share**, then **Connect agent**. Or open the canvas menu and choose **Connect your AI agent**.
+2. Choose **Copy prompt**.
+3. Paste the prompt into your agent.
+
+The prompt tells the agent which canvas to join and how to connect to your catalog.
+
+![The Connect your AI agent dialog](./img/connect-agent.png)
+
+## Set up your client
+
+### Claude
+
+1. Open **Settings → Connectors** and choose **Add custom connector**.
+2. Name it `EventCatalog` and paste your MCP server URL.
+3. In a chat, turn the connector on and ask Claude to join your canvas.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http eventcatalog https://your-eventcatalog.com/docs/mcp
+```
+
+Then ask Claude Code to join your canvas.
+
+### ChatGPT
+
+1. Open **Settings → Apps & Connectors**, turn on developer mode and create a connector with your MCP server URL.
+2. In a chat, add the connector and ask ChatGPT to join your canvas.
+
+### Cursor
+
+```json title=".cursor/mcp.json"
+{
+  "mcpServers": {
+    "eventcatalog": { "url": "https://your-eventcatalog.com/docs/mcp" }
+  }
+}
+```
+
+### VS Code
+
+Use Copilot's agent mode.
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "eventcatalog": { "type": "http", "url": "https://your-eventcatalog.com/docs/mcp" }
+  }
+}
+```
+
+### Agents in your browser
+
+In the **Connect your AI agent** dialog, choose **This browser**, then **Turn on**. Agents in your browser, such as the MCP-B extension, can then use the open canvas through WebMCP.
+
+## The canvas inside your chat
+
+In clients that support [MCP Apps](/docs/development/ask-your-architecture/mcp-server/getting-started#interactive-diagrams-and-schemas), such as Claude and ChatGPT, the agent can open the canvas inside the conversation. You and the agent work on it there, and everyone with the canvas open in EventCatalog sees the same changes.
+
+## Things to ask
+
+**Design ideas together**
+
+- "Add a payments service that listens to OrderPlaced"
+- "How could we split the orders service?"
+- "Add retries and a dead letter queue to this"
+
+**Understand how it works**
+
+- "Put everything the Orders domain owns on the canvas"
+- "Walk me through what happens when a payment fails"
+- "Which services consume this event?"
+
+Agents work from your catalog, so the services and messages they add are the ones your teams document. They talk to you in the chat, and only comment on the canvas when you ask them to, for example to review it.
+
+See the [reference](/docs/development/studio/reference#mcp-tools) for the MCP tools agents use.

package/dist/docs/development/studio/06-run-studio-in-production.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog Studio
+- production
+- deployment
+sidebar_label: Run Studio in production
+title: Run Studio in production
+description: Turn on Studio for a deployed catalog.
+---
+
+Studio is on when you run `eventcatalog dev`. To use it in a deployed catalog, run your catalog in [server mode](/docs/development/deployment/build-ssr-mode) and turn Studio on. Studio isn't available in a static build.
+
+1. In `eventcatalog.config.js`, set `output` to `'server'` and `studio.enabled` to `true`:
+
+   ```js title="eventcatalog.config.js"
+   export default {
+     output: 'server',
+     studio: {
+       enabled: true,
+     },
+   };
+   ```
+
+2. [Set up persistent storage](/docs/development/studio/set-up-persistent-storage). Without it, canvases are lost when the server restarts.
+
+3. Build your catalog and serve it with `eventcatalog start`:
+
+   ```bash
+   npx eventcatalog build
+   npx eventcatalog start
+   ```
+
+## Behind a proxy or load balancer
+
+- **Forward WebSocket connections.** Live collaboration uses a WebSocket on the same port as your catalog.
+- **Trust your HTTPS host.** If your proxy serves the catalog over HTTPS, add your host to `security.allowedDomains`. Otherwise forms such as **New canvas** fail the origin check.
+
+  ```js title="eventcatalog.config.js"
+  export default {
+    output: 'server',
+    security: {
+      allowedDomains: [{ hostname: 'catalog.example.com', protocol: 'https' }],
+    },
+  };
+  ```
+
+## Only let signed-in people in
+
+Turn on [authentication](/docs/development/authentication/introduction). Only signed-in people can then open canvases.
+
+## Turn Studio off
+
+Set `studio.enabled` to `false`. This turns Studio off everywhere, including in `eventcatalog dev`.