@eventcatalog/core 3.39.5 → 3.40.0

package/dist/docs/editor/01-first-edit.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+sidebar_label: First edit tutorial
+title: Make your first edit with EventCatalog Editor
+description: Learn the basic editor workflow by opening a local catalog, changing a resource, previewing it, and reviewing the Git change.
+slug: /editor/first-edit
+---
+
+This tutorial takes you through the first successful editor workflow:
+
+1. Run EventCatalog locally
+2. Run EventCatalog Editor
+3. Open a catalog resource
+4. Make a small documentation change
+5. Preview the resource
+6. Review the Git diff
+7. Publish the change
+
+The goal is not to document a whole architecture. The goal is to learn the editor loop.
+
+::::info Need a catalog?
+
+This tutorial assumes you already have an EventCatalog project on your machine. If you do not, follow the [EventCatalog installation guide](/docs/development/getting-started/installation) first.
+
+::::
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- Node.js 22 or later
+- Git installed
+- An EventCatalog project containing `eventcatalog.config.js`
+- Access to EventCatalog Editor through [EventCatalog Cloud](https://eventcatalog.cloud)
+- A terminal open in or near your catalog project
+
+If a teammate needs access, an organization admin can [invite them as an editor](/docs/editor/how-to/invite-editors).
+
+Check Node and Git with:
+
+```bash
+node -v
+git --version
+```
+
+## Start your EventCatalog preview
+
+Open a terminal in your EventCatalog project and start EventCatalog:
+
+```bash
+npm run dev
+```
+
+By default, EventCatalog runs at [http://localhost:3000](http://localhost:3000).
+
+The editor can still run without a preview, but preview links are only available when EventCatalog is running locally.
+
+## Start the editor
+
+Open another terminal in the same catalog directory and run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor starts on [http://localhost:3900](http://localhost:3900) and opens your browser.
+
+If the editor asks you to sign in, sign in with [EventCatalog Cloud](https://eventcatalog.cloud) and return to the local editor.
+
+## Open a resource
+
+Choose a resource from the left navigation. A good first edit is a [service](/docs/development/guides/services/introduction), [domain](/docs/development/guides/domains/introduction), [event](/docs/development/guides/messages/events/introduction), [command](/docs/development/guides/messages/commands/introduction), or [query](/docs/development/guides/messages/queries/introduction) that already exists in your catalog.
+
+The editor shows:
+
+- The resource list on the left
+- The resource documentation in the center
+- Metadata and relationship fields around the editor
+
+![Service resource open in EventCatalog Editor](./images/editor.png)
+
+## Make a small change
+
+Change a short paragraph, summary, [owner](/docs/owners), badge, or other low-risk field.
+
+The editor writes changes back to your local catalog files. For example, editing a service updates the matching `index.mdx` file in your catalog.
+
+You can use the rich editor for normal writing, or switch to source mode when you need to work directly with Markdown, MDX, or frontmatter.
+
+## Preview the resource
+
+Use **Open Preview** to view the resource in your running EventCatalog site.
+
+![Open Preview button in EventCatalog Editor](./images/open-preview.png)
+
+Preview opens the page from your local EventCatalog development server. If preview is unavailable, check that EventCatalog is running and that the editor detected the correct preview port.
+
+## Review the change
+
+Open **Changes** from the editor navigation.
+
+The changes page groups local Git changes by EventCatalog resource. Open the changed file to inspect the diff.
+
+![Changes page showing a local Git diff](./images/change-diff.png)
+
+## Publish the change
+
+When the diff looks right, click **Publish** in the editor.
+
+In the beta editor, **Publish** commits your changes locally to Git. It does not deploy your catalog or open a pull request.
+
+After publishing, continue with your team's normal review and release workflow. For example, you might push a branch and open a pull request, or push directly if that is how your catalog is maintained.
+
+## What you learned
+
+You have completed the core editor loop:
+
+- Open a local catalog
+- Edit a resource
+- Preview the resource locally
+- Review the Git diff
+- Publish a local commit
+
+Next, learn how to [edit resources](/docs/editor/how-to/edit-resource), [add schemas and specifications](/docs/editor/how-to/add-schemas-and-specifications), or [review and publish changes](/docs/editor/how-to/review-and-commit-changes).

package/dist/docs/editor/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Editor",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "editor",
+    "title": "EventCatalog Editor",
+    "description": "Edit, preview, review, and commit EventCatalog documentation from a local visual editor."
+  }
+}

package/dist/docs/editor/explanation/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Explanation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor explanation",
+    "description": "Conceptual guides that explain how EventCatalog Editor fits with files, Markdown, MDX, Git, and beta access."
+  }
+}

package/dist/docs/editor/explanation/beta-status-feedback.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 3
+sidebar_label: Beta and feedback
+title: Beta status and feedback
+description: Understand the beta status of EventCatalog Editor and how to give feedback.
+---
+
+EventCatalog Editor is in beta.
+
+You can start using it today, but expect some features, workflows, and interface details to change as the product moves toward general availability.
+
+## What beta means
+
+During beta:
+
+- Some workflows may be incomplete
+- Some resource fields may only be editable in source mode
+- Pull request creation and richer publishing flows may change
+- Documentation and screenshots may lag behind fast-moving features
+
+The editor is ready for real feedback, but not every planned workflow is finished.
+
+## Access and seats
+
+EventCatalog Editor is a seat-based paid product.
+
+Community includes 1 editor seat. Starter includes 3 editor seats. Scale includes 10 editor seats. Enterprise includes unlimited editor seats.
+
+Organization admins can [invite editors](/docs/editor/how-to/invite-editors) through [EventCatalog Cloud](https://eventcatalog.cloud). Admin and editor roles use editor seats; viewer roles are free.
+
+See the [pricing page](/pricing) for current plan details.
+
+## Give feedback
+
+The best feedback is specific:
+
+- What you were trying to document
+- What catalog resource you were editing
+- What worked
+- What was confusing
+- What blocked you
+- What you expected the editor to do
+
+Share feedback in the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the editor repository](https://github.com/event-catalog/eventcatalog-editor-code/issues).
+
+## What the beta looks like
+
+![EventCatalog Editor beta interface](../images/editor.png)

package/dist/docs/editor/explanation/how-it-works.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+sidebar_label: How it works
+title: How EventCatalog Editor works
+description: Understand the local architecture and workflow behind EventCatalog Editor.
+---
+
+EventCatalog Editor is local-first.
+
+It starts a small local server, opens a browser UI, reads your EventCatalog project from disk, and writes changes back to the same files.
+
+```mermaid
+flowchart LR
+  A[Browser UI] <--> B[Local editor server]
+  B <--> C[EventCatalog project files]
+  B <--> D[Git repository]
+  B -. detects .-> E[Local EventCatalog preview]
+```
+
+## The editor runs on your machine
+
+The editor binds to your local machine and opens at [http://localhost:3900](http://localhost:3900) by default.
+
+Your catalog stays on disk. Editing a resource changes files in the catalog directory, such as `index.mdx`, schema files, specification files, or `eventcatalog.config.js`.
+
+## The browser talks to the local server
+
+The browser UI does not edit files directly. It talks to the local editor server, which:
+
+- Validates catalog paths
+- Reads resources
+- Writes resource files
+- Manages schema and specification files
+- Reads Git status and diffs
+- Detects local EventCatalog preview URLs
+
+## [EventCatalog Cloud](https://eventcatalog.cloud) controls access
+
+The beta editor uses [EventCatalog Cloud](https://eventcatalog.cloud) for sign-in and editor access.
+
+Organizations in [EventCatalog Cloud](https://eventcatalog.cloud) control which people can open the local editor. Admins and editors can start local editor sessions. Viewers can belong to an organization without using an editor seat, but they cannot open a local editor session.
+
+After sign-in, editing still happens locally. The editor does not become a hosted catalog editor; it remains a local tool pointed at your local catalog files.
+
+## Git remains the review boundary
+
+The editor shows local Git changes, diffs, revert actions, and commits.
+
+It does not replace your team's review and release process. After committing, push and publish the catalog the same way your team already does.

package/dist/docs/editor/explanation/markdown-mdx-git.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+sidebar_label: Markdown, MDX, and Git
+title: Editor, Markdown, MDX, and Git
+description: Understand how the editor works with EventCatalog's file-based authoring model.
+---
+
+EventCatalog is file-based. The editor keeps that model.
+
+Instead of asking every contributor to edit Markdown, MDX, YAML frontmatter, schemas, and Git diffs by hand, the editor gives them a visual workflow on top of the same project files.
+
+## Markdown and MDX are still the source of truth
+
+Each EventCatalog resource is still represented by files in your catalog.
+
+For example, a [service](/docs/development/guides/services/introduction) might live at:
+
+```txt
+domains/Orders/services/OrderService/index.mdx
+```
+
+When you edit that service in the editor, the editor updates the same file.
+
+## Visual editing is an authoring layer
+
+The editor helps with common tasks:
+
+- Writing documentation
+- Changing summaries and owners
+- Adding badges
+- Modeling relationships
+- Adding schemas and specifications
+- Managing draft status
+
+For advanced content, source mode lets you edit the underlying Markdown, MDX, and frontmatter.
+
+## Git shows exactly what changed
+
+Because the editor writes to files, Git can show the exact change.
+
+That makes the editor useful for contributors who prefer a visual workflow while still giving reviewers the normal file diff.
+
+```mermaid
+flowchart LR
+  A[Visual edit] --> B[MDX and schema files]
+  B --> C[Git diff]
+  C --> D[Commit]
+  D --> E[Review and publish]
+```
+
+## Why this matters
+
+This keeps EventCatalog portable:
+
+- You can still edit files in an IDE
+- You can still review changes in pull requests
+- You can still build and deploy with your existing pipeline
+- You can let non-MDX contributors improve documentation safely

package/dist/docs/editor/how-to/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "How-to guides",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor how-to guides",
+    "description": "Task-focused guides for running EventCatalog Editor and working with catalog changes."
+  }
+}

package/dist/docs/editor/how-to/add-schemas-and-specifications.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 7
+sidebar_label: Add schemas and specifications
+title: Add schemas and specifications
+description: Attach message schemas and API specifications from EventCatalog Editor.
+---
+
+Use schemas and specifications to keep implementation contracts close to the architecture resources they describe.
+
+## Add a schema to a message
+
+Schemas are supported on:
+
+- [Events](/docs/development/guides/messages/events/introduction)
+- [Commands](/docs/development/guides/messages/commands/introduction)
+- [Queries](/docs/development/guides/messages/queries/introduction)
+
+Open the message resource, then use the **Schema** section to add or edit the schema file.
+
+Supported schema formats include:
+
+- JSON Schema
+- Avro
+- Protobuf
+- Other text-based schema files
+
+When you save a schema, the editor writes the schema file into the resource folder and updates the resource metadata so EventCatalog can render it.
+
+If the schema editor does not expose the exact change you need yet, use source mode or edit the schema file directly.
+
+## Add a specification to a domain or service
+
+Specifications are supported on:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/services/introduction)
+
+Open the domain or service, then use the specifications area to add:
+
+- OpenAPI
+- AsyncAPI
+- GraphQL
+
+The editor writes the specification file into the resource folder and updates the resource `specifications` metadata.
+
+![Service resource showing attached API specifications](../images/editor.png)
+
+## Preview schema and specification changes
+
+Start EventCatalog locally with:
+
+```bash
+npm run dev
+```
+
+Then use **Open Preview** in the editor to check how the schema or specification renders in the catalog.
+
+## When to use source mode
+
+Use source mode when you need to:
+
+- Adjust a custom `SchemaViewer` component
+- Add custom MDX around a schema
+- Edit specification metadata the visual form does not expose yet
+
+For more on schema documentation in EventCatalog, see the [schema documentation guides](/docs/development/guides/schemas/introduction).

package/dist/docs/editor/how-to/edit-resource.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 4
+sidebar_label: Edit a resource
+title: Edit an EventCatalog resource
+description: Update resource documentation, metadata, relationships, and source content in EventCatalog Editor.
+---
+
+Use this guide when you want to update a resource that already exists in your catalog.
+
+## Open the resource
+
+Start the editor and choose a resource from the resource list.
+
+The editor supports common EventCatalog resource types, including [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/services/introduction), [events](/docs/development/guides/messages/events/introduction), [commands](/docs/development/guides/messages/commands/introduction), [queries](/docs/development/guides/messages/queries/introduction), [channels](/docs/development/guides/channels/introduction), [entities](/docs/development/guides/domains/entities/introduction), [data stores](/docs/development/guides/data/introduction), [flows](/docs/development/guides/flows/introduction), [users](/docs/development/guides/owners/users/introduction), and [teams](/docs/development/guides/owners/teams/introduction).
+
+![Resource list with a service selected](../images/editor.png)
+
+## Edit the documentation
+
+Use the rich editor to change the resource body.
+
+The rich editor supports common writing blocks such as headings, paragraphs, lists, tables, blockquotes, code blocks, links, and dividers.
+
+Use `/` in an empty paragraph to open the block menu. Slash commands also help you insert EventCatalog components such as diagrams, callouts, steps, tiles, prompts, and resource-aware blocks. Learn more in [Use slash commands](/docs/editor/how-to/use-slash-commands).
+
+![Slash command menu showing EventCatalog components](../images/custom-slash-commands.png)
+
+## Edit resource metadata
+
+Use the resource fields to update common frontmatter values such as:
+
+- Name
+- Summary
+- Owners
+- Badges
+- Repository links
+- Draft status
+- Resource image or icon
+
+Some resource types have extra fields. For example, services can model sent and received messages, and data stores can describe type, technology, access mode, classification, retention, and residency.
+
+## Edit relationships
+
+Use relationship fields to connect resources.
+
+For example:
+
+- Add services to a domain
+- Show messages a service sends or receives
+- Connect services to data stores they read from or write to
+- Connect [owners](/docs/owners) to resources
+
+These fields update the same resource metadata that EventCatalog uses when it renders architecture relationships.
+
+## Create related resources
+
+When a relationship field allows new resources, the editor can create the resource and model how it relates to the current resource.
+
+For example, when creating an event from a service, choose whether the service publishes the event, consumes the event, or only contains the event in its folder.
+
+![Create event dialog showing relationship choices](../images/creating-new-event-modal.png)
+
+## Edit flows
+
+Flow resources include a visual Flow Editor for modeling business processes, user journeys, and architecture workflows.
+
+![Flow editor showing a service node in a business flow](../images/flow-editor.png)
+
+Learn how to [use the Flow Editor](/docs/editor/how-to/use-flow-editor).
+
+## Use source mode
+
+Switch to source mode when you need to edit Markdown, MDX, or frontmatter directly.
+
+![Editor source mode showing Markdown and frontmatter](../images/using-source-mode.png)
+
+Source mode is useful for:
+
+- Checking exact frontmatter
+- Editing custom MDX components
+- Making changes the rich editor does not expose yet
+- Copying content from another file
+
+## Save conflicts
+
+If the file changed on disk after the editor loaded it, the editor protects you from overwriting those changes.
+
+Reload the resource, review the external change, and apply your edit again.

package/dist/docs/editor/how-to/invite-editors.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+sidebar_label: Invite editors
+title: Invite editors to your organization
+description: Add team members in EventCatalog Cloud and assign editor seats so they can use EventCatalog Editor locally.
+---
+
+Use [EventCatalog Cloud](https://eventcatalog.cloud) to manage who can use EventCatalog Editor.
+
+The editor still runs locally on each person's machine. Cloud verifies that the person belongs to your organization and has a role that can open a local editor session.
+
+![Invite team members in EventCatalog Cloud](../images/invite-team-members.png)
+
+## Before you start
+
+You need:
+
+- An [EventCatalog Cloud](https://eventcatalog.cloud) organization
+- Admin access to that organization
+- An available editor seat if you want to invite another admin or editor
+
+If you have not created an organization yet, sign in to [EventCatalog Cloud](https://eventcatalog.cloud) and complete the organization setup first.
+
+## Editor seats by plan
+
+Editor seats control how many people can use EventCatalog Editor for an organization.
+
+- Community includes 1 editor seat
+- Starter includes 3 editor seats
+- Scale includes 10 editor seats
+- Enterprise includes unlimited editor seats
+
+Admins and editors use editor seats. Viewers are free, but viewers cannot open a local editor session.
+
+You can compare plans on the [pricing page](/pricing).
+
+## Invite a team member
+
+1. Sign in to [EventCatalog Cloud](https://eventcatalog.cloud).
+2. Open the organization you want the editor to use.
+3. Go to **Team**.
+4. Enter the team member's email address.
+5. Choose their role.
+6. Click **Invite**.
+
+Invitations expire after 7 days.
+
+Pending invitations for admin and editor roles count toward your editor seat usage. If you run out of editor seats, invite the person as a viewer, cancel an unused pending invitation, change an existing member's role, or upgrade your plan.
+
+## Choose the right role
+
+- Admin can manage the organization, invite members, and use EventCatalog Editor.
+- Editor can use EventCatalog Editor for the organization.
+- Viewer can belong to the organization without using an editor seat.
+
+Use **Editor** for most people who need to maintain catalog content. Use **Admin** when the person also needs to manage organization settings and team access.
+
+## What the invited person does next
+
+After accepting the invitation, the team member can:
+
+1. Clone or open the EventCatalog project locally.
+2. Install catalog dependencies if needed.
+3. [Run EventCatalog Editor locally](/docs/editor/how-to/run-locally).
+4. Sign in with [EventCatalog Cloud](https://eventcatalog.cloud) when the editor asks for access.
+5. Choose the organization if their account belongs to more than one organization.
+
+The editor changes their local files and gives them a Git UI to publish a local commit. It does not upload catalog source files to [EventCatalog Cloud](https://eventcatalog.cloud).

package/dist/docs/editor/how-to/open-catalog.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+sidebar_label: Open a catalog
+title: Open a catalog in the editor
+description: Mount an EventCatalog project from the CLI or from the editor UI.
+---
+
+EventCatalog Editor needs a local catalog directory before it can show resources.
+
+## How the editor finds a catalog
+
+When you run `npx @eventcatalog/editor`, the editor looks for a catalog in this order:
+
+1. The path passed with `--catalog`
+2. The current directory, if it contains `eventcatalog.config.js`
+3. The first child directory containing `eventcatalog.config.js`
+4. The catalog path screen in the browser
+
+## Open a catalog from the CLI
+
+Pass the catalog path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+Use an absolute path when possible. It makes it clear which catalog the editor is changing.
+
+## Open a catalog from the browser
+
+If the editor cannot find a catalog automatically, it shows a catalog path screen.
+
+Enter the path to your EventCatalog project and choose **Open**.
+
+## Fix catalog loading errors
+
+If the editor cannot open the catalog, check that:
+
+- The path points to the catalog root
+- The directory contains `eventcatalog.config.js`
+- The config file can be imported by Node.js
+- Dependencies for the catalog are installed
+
+If you are not sure what the catalog root should look like, read the [EventCatalog project structure guide](/docs/development/getting-started/project-structure).

package/dist/docs/editor/how-to/preview-changes.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 8
+sidebar_label: Preview changes
+title: Preview editor changes
+description: Open local EventCatalog preview links from the editor.
+---
+
+Preview lets you check how a resource looks in EventCatalog before committing your changes.
+
+## Start EventCatalog locally
+
+In your catalog project, run:
+
+```bash
+npm run dev
+```
+
+EventCatalog usually runs at [http://localhost:3000](http://localhost:3000).
+
+## Start the editor
+
+In another terminal, run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor checks whether EventCatalog is running locally. When it detects a preview, resource pages show **Open Preview**.
+
+## Use a custom preview port
+
+If EventCatalog is running on a different port, tell the editor:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+## Open a preview
+
+Open a resource in the editor and choose **Open Preview**.
+
+The editor opens the matching resource page in the local EventCatalog site.
+
+![Editor header with Open Preview action](../images/header.png)
+
+## Fix missing preview links
+
+If preview is unavailable:
+
+- Check that EventCatalog is running
+- Check the preview port
+- Restart the editor after starting EventCatalog
+- Open the local EventCatalog URL directly to confirm it works
+
+Preview is local. It does not publish your changes.

package/dist/docs/editor/how-to/revert-local-changes.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 10
+sidebar_label: Revert local changes
+title: Revert local editor changes
+description: Discard local catalog edits from the editor changes view.
+---
+
+Use revert when you want to discard local edits before committing them.
+
+## Open the Changes page
+
+Choose **Changes** from the editor navigation.
+
+The editor shows modified, added, deleted, renamed, and untracked files when Git change tracking is available.
+
+## Revert one file
+
+Open a changed file and choose **Revert**.
+
+The editor asks for confirmation before it discards the local file change.
+
+![Changes page with revert actions for local edits](../images/change-diff.png)
+
+## Revert a resource group
+
+If a resource has multiple changed files, you can revert the group from the Changes page.
+
+For example, reverting a message resource might discard changes to both:
+
+- `index.mdx`
+- `schema.json`
+
+## What revert does
+
+Revert restores modified and deleted files from Git.
+
+Untracked files are removed from disk.
+
+::::warning Revert cannot be undone by the editor
+
+Only revert files when you are sure you do not need the local edits. If you are unsure, inspect the diff first or commit the work to a temporary branch.
+
+::::