@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/plugins/graphql/01-installation.md

@@ -74,34 +74,34 @@ generators: [
 
 ### Configure license key
 
-The EventCatalog GraphQL plugin requires a license key to work with EventCatalog.
+The EventCatalog GraphQL plugin requires an EventCatalog Scale license key to work with EventCatalog.
 
-You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
 
 You have a few options for setting the license key:
 
 1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
 2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
 
-#### 1. Setting license key in `.env` file (recommended)
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
 
 Create a `.env` file in the root of your project and add the following:
 
 ```bash title=".env"
-EVENTCATALOG_LICENSE_KEY_GRAPHQL=your-license-key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
 ```
 
-:::tip Using an older version of EventCatalog?
+:::tip Using an Older API Key?
 
-If you are using an older version of EventCatalog that does not support the `.env` file, you can just export the license key as an environment variable.
+If you already have an older GraphQL plugin key, you can still use it with the GraphQL-specific environment variable.
 
-```bash title="Setting license key in environment variables"
-export EVENTCATALOG_LICENSE_KEY_GRAPHQL=your-license-key
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_GRAPHQL=your-license-key
 ```
 
 :::
 
-#### 2. Setting license key in eventcatalog.config.js
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
 
 If you prefer, you can set the license key in the `eventcatalog.config.js` file
 using the `licenseKey` property in the EventCatalog GraphQL plugin.
@@ -112,7 +112,7 @@ export default {
     [
       '@eventcatalog/generator-graphql',
       {
-        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_GRAPHQL
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
       },
     ],
   ],
@@ -141,4 +141,4 @@ npm run dev
 
 ## Any questions or need help?
 
-If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).

package/dist/docs/plugins/graphql/02-plugin-configuration.md

@@ -21,7 +21,7 @@ The EventCatalog GraphQL plugin is configured in the `eventcatalog.config.js` fi
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `services` | `Service[]` | Yes | List of GraphQL schema files to add to your catalog, and the service name and version |
-| `licenseKey` | string | Yes* | License key for the plugin. Get a 14-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via `EVENTCATALOG_LICENSE_KEY_GRAPHQL` environment variable. |
+| `licenseKey` | string | Yes* | EventCatalog Scale license key. Get a 30-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
 
 ### Service Configuration
 
@@ -36,8 +36,8 @@ Each service in the `services` array requires the following properties:
 | `name` | string | No | Display name for the service. If not provided, the `id` will be used. |
 | `summary` | string | No | Short summary of the service. |
 | `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
-| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service writes to. (Added in v0.4.4) |
-| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service reads from. (Added in v0.4.0) |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v0.4.4) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v0.4.0) |
 
 ## Optional Configuration Options
 
@@ -124,4 +124,3 @@ export default {
 ```
 
 You can view an example configuration in the [EventCatalog GraphQL plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-graphql/basic/eventcatalog.config.js).
-

package/dist/docs/plugins/graphql/03-features.md

@@ -17,7 +17,7 @@ import TabItem from '@theme/TabItem';
 | [Assign owners to your domains, services and messages](#assign-owners-to-your-domains-services-and-messages) | You can assign owners (teams or individuals) to your GraphQL services and all the messages that are generated from your schema. This helps with accountability and contact information for your APIs. |
 | [Automatic versioning](#automatic-versioning) | When you change versions in your GraphQL schema and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between schema versions. |
 | [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | You can create draft domains, services and messages in EventCatalog from your GraphQL schemas. This will be used to mark the resources as draft in EventCatalog. |
-| [Persist markdown](#persist-markdown) | When you generate your GraphQL schemas your markdown on your domains, services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your schemas. |
+| [Persist markdown](#persist-markdown) | When you generate your GraphQL schemas your markdown on your domains, services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your schemas. |
 | [Displaying schemas](#displaying-schemas) | EventCatalog will document your GraphQL schemas and allow users to download them. Your schema files are versioned alongside your services and messages. |
 
 ### Mapping operations as queries, mutations, or subscriptions
@@ -56,9 +56,9 @@ type User {
 
 When this schema is processed by the GraphQL generator:
 
-- **Queries** like `getUser` and `getAllUsers` will be documented as [queries](/docs/development/guides/messages/queries/introduction)
-- **Mutations** like `createUser`, `updateUser`, and `deleteUser` will be documented as [commands](/docs/development/guides/messages/commands/introduction)
-- **Subscriptions** like `userUpdated` and `userDeleted` will be documented as [events](/docs/development/guides/messages/events/introduction)
+- **Queries** like `getUser` and `getAllUsers` will be documented as [queries](/docs/development/guides/resources/messages/message-types/queries)
+- **Mutations** like `createUser`, `updateUser`, and `deleteUser` will be documented as [commands](/docs/development/guides/resources/messages/message-types/commands)
+- **Subscriptions** like `userUpdated` and `userDeleted` will be documented as [events](/docs/development/guides/resources/messages/message-types/events)
 
 Each operation becomes a message in EventCatalog with:
 - The operation name as the message ID

package/dist/docs/plugins/openapi/00-intro.md

@@ -53,11 +53,11 @@ The EventCatalog OpenAPI plugin let's you define 1 or many OpenAPI files. When r
 
 ## Commercial and License
 
-This plugin requires a license key to be used. 
+This plugin requires an EventCatalog Scale license key to be used.
 
-You can get a 14 day trial license key to try the plugin out by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
 
-After the trial you can purchase a license to continue using this plugin, we have different plans to suit your organization. 
+After the trial, you can continue using this plugin with EventCatalog Scale. 
 
 See [pricing](/pricing) for more information.
 
@@ -66,13 +66,13 @@ _Have any questions? You can email us at `hello@eventcatalog.dev`._
 ## License FAQ
 
 ### What is the license key for?
-The license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+The EventCatalog Scale license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
 
-### How do I get a license key?
-You can obtain a license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 14-day free trial.
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
 
 ### Terms
-- **Trial Period**: 14 days free trial no credit card required
+- **Trial Period**: 30-day free trial no credit card required
 - **Support**: Discord community support (extra for priority support)
 
-After your trial period ends, you can purchase a full license through [EventCatalog Cloud](https://eventcatalog.cloud) to continue using the plugin.
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).

package/dist/docs/plugins/openapi/01-installation.md

@@ -72,31 +72,31 @@ generators: [
 
 ### Configure license key
 
-The EventCatalog OpenAPI plugin requires a license key to work with EventCatalog.
+The EventCatalog OpenAPI plugin requires an EventCatalog Scale license key to work with EventCatalog.
 
-You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
 
 You have a few options for setting the license key: 
 
 1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
 2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
 
-#### 1. Setting license key in `.env` file (recommended)
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
 
 <AddedIn version="2.35.4" />
 
 Create a `.env` file in the root of your project and add the following:
 
 ```bash title=".env"
-EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
 ```
 
-:::tip Using an older version of EventCatalog?
+:::tip Using an Older API Key?
 
-If you are using an older version of EventCatalog that does not support the `.env` file, you can just export the license key as an environment variable.
+If you already have an older OpenAPI plugin key, you can still use it with the OpenAPI-specific environment variable.
 
-```bash title="Setting license key in environment variables"
-export EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
 ```
 
 :::
@@ -106,7 +106,7 @@ export EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
 
 If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
 
-#### 2. Setting license key in eventcatalog.config.js
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
 
 If you prefer, you can set the license key in the `eventcatalog.config.js` file
 using the `licenseKey` property in the EventCatalog OpenAPI plugin.
@@ -117,7 +117,7 @@ export default {
     [
       '@eventcatalog/generator-openapi',
       {
-        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_OPENAPI
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
       },
     ],
   ],
@@ -145,4 +145,3 @@ npm run dev
 If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
 
 
-

package/dist/docs/plugins/openapi/02-plugin-configuration.md

@@ -22,7 +22,7 @@ The EventCatalog OpenAPI plugin is configured in the `eventcatalog.config.js` fi
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `services` | `Service[]` | Yes | List of OpenAPI files to add to your catalog |
-| `licenseKey` | string | Yes* | License key for the plugin. Get a 14-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via `EVENTCATALOG_LICENSE_KEY_OPENAPI` environment variable. |
+| `licenseKey` | string | Yes* | EventCatalog Scale license key. Get a 30-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
 
 
 ### Service Configuration
@@ -33,14 +33,15 @@ Each service in the `services` array requires the following properties:
 |----------|------|----------|-------------|
 | `id` | string | Yes | EventCatalog ID for the service. |
 | `path` | string or string[] | Yes | Path/s to your OpenAPI file or remote URL to the OpenAPI file. v6.0.0 introduced the ability to map multiple OpenAPI files to a single service. |
+| `version` | string | No | Version for the generated EventCatalog service and messages. If not provided, the version from the OpenAPI `info.version` field is used. |
 | `name` | string | No | Display name for the service. If not provided, the specification will be used. _Added in v7.4.3_|
 | `summary` | string | No | Short summary of the service. If not provided, the specification will be used. _Added in v7.4.3_|
 | `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. |
 | `setMessageOwnersToServiceOwners` | boolean | No | If true, the owners of the service will be set to the owners of the messages in the OpenAPI file (default is true). |
 | `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
 | `draft` | boolean | No | If true, the service will be drafted in EventCatalog with all it's endpoints / messages. (Added in v7.3.0) |
-| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service writes to. (Added in v7.5.0) |
-| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/data/introduction) id and version (optional) that the service reads from. (Added in v7.5.0) |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v7.5.0) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v7.5.0) |
 | `headers` | `Record<string, string>` | No | HTTP headers for authenticated remote URLs (e.g., `{ Authorization: 'Bearer token' }`). Used when fetching OpenAPI files from URLs that require authentication. |
 | `consumers` | `ConsumerService[]` | No | Services that consume messages generated from this OpenAPI spec. Each entry requires an `id`, and supports an optional `version` and `routes` filter. See [consumer services](/docs/plugins/openapi/features#define-consumer-services) for details. |
 
@@ -64,7 +65,7 @@ Each service in the `services` array requires the following properties:
 | `writeFilesToRoot` | boolean | `false` | Write OpenAPI messages to root instead of service folder. By default all domains, services and messages 
 will be grouped in the folder directory structure. |
 | `saveParsedSpecFile` | boolean | `false` | Parse and save expanded OpenAPI spec (helpful for files with $refs) |
-| `sidebarBadgeType` | string | `HTTP_METHOD` | (Added in v5.0.1) Decides what badges are shown in the [documentation sidebar](/docs/development/customization/customize-sidebars/documentation-sidebar). `HTTP_METHOD` shows HTTP methods as badges, `MESSAGE_TYPE` shows `QUERY`, `COMMAND` or `EVENT` as badges. |
+| `sidebarBadgeType` | string | `HTTP_METHOD` | (Added in v5.0.1) Decides what badges are shown in the [documentation sidebar](/docs/development/customization/documentation-sidebar). `HTTP_METHOD` shows HTTP methods as badges, `MESSAGE_TYPE` shows `QUERY`, `COMMAND` or `EVENT` as badges. |
 | `httpMethodsToMessages` | object | - | (Added in v5.0.2) Gives you the ability to map HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc.) to message types (`command`, `query`, `event`). By default OpenAPI will map your requests to queries, you can use this property to change this behavior or use the `x-eventcatalog-message-type` extension to set the message type for each request. **If you use the `x-eventcatalog-message-type` extension in your spec file, this will be used.** |
 | `preserveExistingMessages` | boolean | true | (Added in v5.0.5) If true, the existing message markdown is preserved on new generation (default is true). Setting to false will always write the message markdown from the OpenAPI spec file. |
 | `parseExamples` | boolean | true | <AddedIn version="7.9.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/> When enabled, parses examples from OpenAPI operations (request body and response examples) and writes them to each message's `examples` folder as JSON files. Set to `false` to disable. |
@@ -110,7 +111,8 @@ export default {
         services: [
           { 
             path: path.join(__dirname, 'openapi-files', 'orders-service.yml'),
-            id: 'orders-service'
+            id: 'orders-service',
+            version: '1.0.0'
           }
         ],
         domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
@@ -329,4 +331,3 @@ or refer to the [OpenAPI examples on GitHub](https://github.com/event-catalog/ge
 
 
 
-

package/dist/docs/plugins/openapi/03-features.md

@@ -28,7 +28,7 @@ import TabItem from '@theme/TabItem';
 | [Define EventCatalog ids and names in your OpenAPI specification file](#define-eventcatalog-ids-and-names-in-your-openapi-specification-file) | EventCatalog messages (commands, queries and events) have two important properties, these are `id` and `name`. |
 | [Define messages a service sends or receives](#define-messages-a-service-sends-or-receives) | **By default all messages in your OpenAPI spec file are documented as messages that are received by your service** (e.g a route with /getOrders will be a query/command/event that the service accepts). You can override this by using the `x-eventcatalog-message-action` extension. |
 | [Deprecating messages](#deprecating-messages) | To mark messages as deprecated you can use the `deprecated` field or the `x-eventcatalog-deprecated-date` and `x-eventcatalog-deprecated-message` extensions. |
-| [Persist markdown](#persist-markdown) | When you generate your OpenAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files. |
+| [Persist markdown](#persist-markdown) | When you generate your OpenAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files. |
 | [Automatic versioning](#automatic-versioning) | When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI files, schemas and more. |
 | [Downloading schemas](#downloading-schemas) | If your messages have schemas EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema. |
 | [Parse examples from operations](#parse-examples-from-operations) | Automatically extract request body and response examples from your OpenAPI operations and save them as JSON files alongside your messages in EventCatalog. |
@@ -595,13 +595,13 @@ This will render a banner in EventCatalog indicating that the message will be de
 
 When you generate your OpenAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions.
 
-This allows you to add [custom components](/docs/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files.
+This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files.
 
 ### Automatic versioning
 
 When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI files, schemas and more.
 
-You can also add changelogs between different versions of your services and messages. [Read here for more information](/docs/development/guides/messages/common/changelog).
+You can also add changelogs between different versions of your services and messages. [Read here for more information](/docs/development/guides/resources/messages/versioning-and-lifecycle/add-changelog).
 
 ### Downloading schemas
 
@@ -613,11 +613,11 @@ The service that is also generated will allow you to see and download the OpenAP
 
 <AddedIn version="7.12.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
 
-When a service sends or receives many messages, the [visualiser](/docs/development/guides/messages/common/grouping-messages) can become crowded. The `groupMessagesBy` option lets you automatically group related messages together so they collapse into a single node in the visualiser map, making your architecture easier to understand at a glance.
+When a service sends or receives many messages, the [visualiser](/docs/development/guides/resources/messages/connect-messages/group-messages) can become crowded. The `groupMessagesBy` option lets you automatically group related messages together so they collapse into a single node in the visualiser map, making your architecture easier to understand at a glance.
 
 ![Message group expanded in the visualiser](./img/message-group-expanded.png)
 
-To learn more about how groups work in the visualiser, see [Grouping messages](/docs/development/guides/messages/common/grouping-messages).
+To learn more about how groups work in the visualiser, see [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages).
 
 Three strategies are supported:
 
@@ -696,7 +696,7 @@ generators: [
 This is useful for very large APIs where `path-prefix` still leaves too many ungrouped nodes. Every message collapses into a single `operations` node in the visualiser.
 
 :::tip
-Once grouped, messages appear as a compact stacked card in the visualiser. Click the group to expand it and see the full downstream graph — channels, consumers, and producers — just as if the messages were ungrouped. See [Grouping messages](/docs/development/guides/messages/common/grouping-messages) for more details.
+Once grouped, messages appear as a compact stacked card in the visualiser. Click the group to expand it and see the full downstream graph — channels, consumers, and producers — just as if the messages were ungrouped. See [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages) for more details.
 :::
 
 ---
@@ -787,4 +787,3 @@ generators: [
   ],
 ],
 ```
-

package/dist/docs/tutorial/01-start-here.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 1
+slug: /tutorial
+sidebar_label: Introduction
+title: Introduction
+description: Learn what you will build in the EventCatalog tutorial.
+---
+
+In this tutorial, you will build your first EventCatalog from a small commerce architecture.
+
+The goal is to get you from a blank project to a working catalog you can open in the browser and understand how EventCatalog works.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/tutorial-introduction.png"
+    alt="The tutorial catalog overview page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The catalog you will build during this tutorial.
+  </figcaption>
+</figure>
+
+## What we are building
+
+We are going to document a small order flow for an e-commerce system.
+
+The system is simple on purpose. A customer places an order, one service publishes an event, another service consumes it, and the catalog explains how those pieces connect.
+
+You will build the first version of that catalog by adding:
+
+| Resource | Tutorial example |
+| --- | --- |
+| Domain | E-Commerce |
+| Service | OrderService |
+| Event | OrderPlaced |
+| Consumer | InventoryService |
+| Schema | schema.json |
+| Owner | Commerce Platform Team |
+
+By the end of the tutorial, you will have:
+
+- created a new EventCatalog project
+- run the catalog locally
+- found domains, services, messages, schemas, owners, and visualizations in the UI
+- added a domain, service, event, schema, owner, producer, and consumer
+- used EventCatalog to answer who owns an event and which services produce or consume it
+- built the catalog so it can be shared with your team
+
+This will not cover every EventCatalog feature. It gives you a clear first path through the product, then points you to the next places to go.
+
+## How EventCatalog docs work
+
+EventCatalog pages are written with [MDX](https://mdxjs.com/). That means you can write normal Markdown, and when you need something richer, you can add components directly into the page.
+
+Most catalog resources also have frontmatter at the top of the file. Frontmatter is where EventCatalog reads structured information like the resource `id`, `name`, `version`, owners, schemas, producers, consumers, and domain relationships.
+
+You will use both in this tutorial:
+
+- Markdown for the human-readable documentation.
+- Frontmatter for the architecture metadata EventCatalog uses to build relationships.
+- [EventCatalog components](/docs/development/components/using-components) for richer views, such as schemas and visualizations.
+
+You can learn more about [custom documentation and frontmatter](/docs/development/bring-your-own-documentation/custom-pages/adding-custom-docs), or come back to those docs after you finish this first catalog.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/) v22 or higher installed.
+- Operating systems: macOS, Windows including WSL, or Linux.
+
+You do not need to know EventCatalog before starting.
+
+## Next step
+
+Continue to [Install EventCatalog](/docs/tutorial/install-eventcatalog).

package/dist/docs/tutorial/02-install-eventcatalog.md

@@ -0,0 +1,98 @@
+---
+sidebar_position: 2
+sidebar_label: Install EventCatalog
+title: Install EventCatalog
+description: Create a new EventCatalog project from the command line.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create an empty EventCatalog project and run it locally.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'terminal',
+      text: 'Create an empty EventCatalog project from the command line.',
+    },
+    {
+      icon: 'folder',
+      text: 'Review the files and folders created for a blank catalog.',
+    },
+    {
+      icon: 'eye',
+      text: 'Start EventCatalog and open the empty catalog in your browser.',
+    },
+  ]}
+/>
+
+### Create an empty catalog
+
+Run:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
+```
+
+The `--empty` flag creates a clean catalog without sample domains, services, or messages. This gives us a blank project to build on during the tutorial.
+
+### Project structure
+
+After the install finishes, your empty catalog should look similar to this:
+
+<ProjectTree
+  items={[
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'logo.png' }],
+    },
+    { name: '.env' },
+    { name: 'AGENTS.md' },
+    { name: 'CLAUDE.md' },
+    { name: 'eventcatalog.auth.js' },
+    { name: 'eventcatalog.config.js', highlight: true },
+    { name: 'eventcatalog.styles.css' },
+    { name: 'package.json', highlight: true },
+  ]}
+/>
+
+For this tutorial, most of your work will happen in new folders that you create later. You will also come back to `eventcatalog.config.js` when you need to change catalog configuration.
+
+### Start EventCatalog
+
+Run commands in your new catalog directory
+
+```bash
+cd my-catalog
+```
+
+Run:
+
+```bash
+npm run dev
+```
+
+Open the local URL shown in your terminal. It is usually:
+
+```txt
+http://localhost:3000
+```
+
+### Expected result
+
+You should see a working EventCatalog site in your browser.
+
+The catalog will be mostly empty. That is expected. In the next steps, you will add the architecture yourself.
+
+<figure style={{ textAlign: "center" }}>
+  <img src="/img/tutorial/empty-catalog-home.png" alt="An empty EventCatalog running locally in the browser" style={{ display: "block", margin: "0 auto" }} />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>An empty EventCatalog running locally. Your catalog will start with very little content.</figcaption>
+</figure>
+
+
+### Next
+
+Continue to [Create a service](/docs/tutorial/create-a-service).