@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/federation/reference/troubleshooting.md

@@ -0,0 +1,208 @@
+---
+sidebar_position: 6
+sidebar_label: Troubleshooting
+title: Troubleshooting EventCatalog Federation
+description: Fix common source, ownership, relationship, asset, cache, and generated-output problems.
+---
+
+import EventCatalogEnterprise from '@site/src/components/MDX/EventCatalogEnterprise';
+
+<EventCatalogEnterprise />
+
+Run with verbose diagnostics before investigating a warning:
+
+```bash
+npx eventcatalog federate --verbose
+```
+
+Errors always include details. Verbose mode adds the attributes for warnings.
+
+## Federation is not enabled
+
+If the command reports that Federation is an Enterprise feature:
+
+- Confirm the Enterprise `license.jwt` file is in the central catalog root
+- If the file is stored elsewhere, confirm `EC_LICENSE` points to it
+- Confirm the license has not expired
+- Email [hello@eventcatalog.dev](mailto:hello@eventcatalog.dev?subject=EventCatalog%20Federation%20Trial) to request or replace an offline trial key
+- Review [offline license validation](/docs/development/license-keys/license-validation#offline-validation)
+
+## No sources are configured
+
+Add at least one entry to `federation.sources`:
+
+```js title="eventcatalog.config.js"
+export default {
+  federation: {
+    sources: [
+      {
+        id: 'acme/payments',
+        source: 'github:acme/payments-catalog',
+      },
+    ],
+  },
+};
+```
+
+If previous Federation output exists, an empty source list intentionally removes it and its managed public files.
+
+## A source ID is configured more than once
+
+Every source entry needs a unique stable `id`. Change or remove the duplicate configuration entry.
+
+This configuration error is different from `federation/duplicate-source`, which means several catalogs own the same resource ID.
+
+## GitHub source errors
+
+### Unsupported GitHub locator
+
+Use:
+
+```text
+github:owner/repository
+```
+
+Do not use a full `https://github.com/...` URL.
+
+### Repository cannot be fetched
+
+Check:
+
+- The owner and repository name
+- The configured `ref`
+- Network access to GitHub
+- Git is installed when the source does not publish an index
+- `EVENTCATALOG_GITHUB_TOKEN` or `GITHUB_TOKEN` has repository contents read access
+
+### Published index source does not match
+
+The `source` value inside `catalog.index.json` must equal the configured source `id`.
+
+Either correct the published index or configure the matching stable ID.
+
+### Catalog path escapes the source
+
+`path` must be a safe relative path inside the selected repository. Remove absolute paths, `..` segments, or backslashes.
+
+## Filesystem source errors
+
+### Source does not exist
+
+`file:` paths are resolved from the central catalog directory, not from the terminal's parent directory.
+
+For sibling catalogs:
+
+```js
+{
+  id: 'acme/payments',
+  source: 'file:../payments-catalog',
+}
+```
+
+Confirm that the resolved directory exists and contains an EventCatalog project.
+
+### Filesystem source does not support `ref`
+
+Remove `ref` from the source. Filesystem sources always read the current local files.
+
+### Source or artifact escapes its allowed directory
+
+Federation rejects paths and symbolic links that resolve outside the selected filesystem source. Keep the catalog and its referenced files within the source root.
+
+## Ownership and type errors
+
+### `federation/duplicate-source`
+
+Several catalogs own the same resource ID. Choose one owner and remove copied or placeholder definitions from the other catalogs.
+
+### `federation/type-collision`
+
+The same ID is documented with different resource types. Correct the type or assign distinct IDs.
+
+### `federation/pointer-type-mismatch`
+
+A relationship expects one type but resolves to another. Correct the relationship pointer or its target ID.
+
+Use the [diagnostic rule reference](/docs/federation/reference/diagnostic-rules) to interpret the printed attributes.
+
+## Relationship warnings
+
+### Referenced resource does not exist
+
+For `federation/missing-resource`:
+
+- Check the referenced ID for a typo
+- Add the owning catalog to `federation.sources`
+- Confirm the owner documents the resource
+- Keep the warning if the external reference is deliberate
+
+### Referenced resource version does not exist
+
+For `federation/unresolved-version`:
+
+- Compare `requested version` with `available versions`
+- Correct the exact version or semantic range
+- Publish the required version in the owning catalog
+
+## Public assets or components are not correct
+
+For `federation/asset-collision`, run with `--verbose` to see the source order and winner.
+
+Then:
+
+- Namespace remote asset paths by team or domain
+- Make intentionally shared files identical
+- Reorder sources only when last-source-wins is deliberate
+- Check whether the central catalog owns the public path
+- Check whether a local component overrides the federated component
+
+If a custom component imports an npm package, install that dependency in the central catalog.
+
+Top-level source `snippets/` are not currently federated. Move required content into the page, provide it centrally, or avoid the remote snippet import.
+
+## Content hash mismatch
+
+Federation fetched bytes that did not match the hash recorded by the source index.
+
+Rerun the command first. If the error remains:
+
+- Regenerate or remove a stale published `catalog.index.json`
+- Confirm the source content still exists at the indexed commit
+- Check whether content was changed without updating the index
+
+Federation does not install content that fails integrity validation.
+
+## The lockfile cannot be read
+
+Check that `eventcatalog.lock` contains valid JSON and was not partially edited.
+
+If you do not need its audit or managed public-file state, move the malformed file aside and rerun Federation. Review public assets carefully because the new run will not know which existing files were managed by the unreadable lockfile.
+
+## Federated content looks stale
+
+Run Federation again before starting or building EventCatalog:
+
+```bash
+npx eventcatalog federate
+npm run dev
+```
+
+For a local source, remember there is no watcher integration yet.
+
+Use `--no-cache` when investigating cache behavior:
+
+```bash
+npx eventcatalog federate --no-cache
+```
+
+The cache is content-addressed and verified, so changing source content normally produces a different cache key without this option.
+
+## A failed run left the previous content visible
+
+This is expected. Federation preserves or restores the previous successful output when validation or a normal output update fails.
+
+Fix the reported problem and rerun the command. New output and a new lockfile are installed only after Federation succeeds.
+
+## Get help
+
+Share the command output, relevant source configuration with secrets removed, and the expected ownership model in the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue](https://github.com/event-catalog/eventcatalog/issues).

package/dist/docs/plugins/01-intro.md

@@ -29,11 +29,11 @@ These plugins are maintained by the EventCatalog team and are updated regularly,
 - [OpenAPI Plugin](/docs/plugins/openapi/intro) - Generate documentation from your OpenAPI files
 - [GraphQL Plugin](/docs/plugins/graphql/intro) - Generate documentation from your GraphQL files
 - [Github Plugin](/docs/plugins/github/intro) - Sync your schemas from GitHub to EventCatalog
-- [Backstage Plugin](/docs/plugins/backstage/intro) - Use EventCatalog features within Backstage
+- [Backstage Plugin](/docs/plugins/backstage/overview) - Embed EventCatalog documentation and visualizations in Backstage
 - [Amazon EventBridge](/docs/plugins/eventbridge/intro) - Sync Amazon EventBridge schemas to EventCatalog
 - [Amazon API Gateway](/docs/plugins/amazon-apigateway/intro) - Generate documentation from your Amazon API Gateway
 - [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) - Sync your schemas from Confluent Schema Registry to EventCatalog
-- [EventCatalog Federation](/docs/plugins/eventcatalog-federation/introduction) - Merge multiple EventCatalog instances into a single catalog.
+- [EventCatalog Federation](/docs/federation/overview) - Merge multiple EventCatalog instances into a single catalog.
 
 #### Community plugins
 
@@ -46,4 +46,4 @@ EventCatalog can integrate with anything that has an API.
 
 We offer support and services to build custom integrations for your EventCatalog.
 
-If you would like to explore custom integrations and have us build your integrate for you please contact us at `hello@eventcatalog.dev`.
+If you would like to explore custom integrations and have us build your integrate for you please contact us at `hello@eventcatalog.dev`.

package/dist/docs/plugins/03-all-plugins.md

@@ -19,8 +19,8 @@ Automate and sync your data from a wide range of systems to EventCatalog.
 | [Apicurio Registry](/docs/plugins/apicurio/intro) | Import schemas and specifications from Apicurio Registry into EventCatalog |
 | [Azure Schema Registry](/docs/plugins/azure-schema-registry/intro) | Import schemas from Azure Schema Registry into EventCatalog |
 | [Github Plugin](/docs/plugins/github/intro) | Sync your schemas from GitHub to EventCatalog |
-| [Backstage Plugin](/docs/plugins/backstage/intro) | Use EventCatalog features within Backstage |
+| [Backstage Plugin](/docs/plugins/backstage/overview) | Embed EventCatalog documentation and visualizations in Backstage |
 | [Amazon EventBridge](/docs/plugins/eventbridge/intro) | Sync Amazon EventBridge schemas to EventCatalog |
 | [Amazon API Gateway](/docs/plugins/amazon-apigateway/intro) | Generate documentation from your Amazon API Gateway |
 | [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) | Sync your schemas from Confluent Schema Registry to EventCatalog |
-| [EventCatalog Federation](/docs/plugins/eventcatalog-federation/introduction) | Merge multiple EventCatalog instances into a single catalog. |
+| [EventCatalog Federation](/docs/federation/overview) | Merge multiple EventCatalog instances into a single catalog. |

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

@@ -38,10 +38,10 @@ The EventCatalog AsyncAPI plugin can provide you with many features:
 - ⭐️ Generate domains, services and messages into your catalog from your AsyncAPI specification files
 - ⭐️ [Automate your EventCatalog and fetch AsyncAPI files by URL](/docs/plugins/asyncapi/features#fetch-asyncapi-files-by-url)
 - ⭐️ [Map commands, queries and events from your OpenAPI file using custom extensions](/docs/plugins/asyncapi/features#mapping-messages-events-commands-or-queries)
-- ⭐️ [Automatically version your changes in EventCatalog in sync with your AsyncAPI versions](#automatic-versioning)
-- ⭐️ [Allow you to write and persist custom markdown between changes](#persist-markdown)
-- ⭐️ [Display your message schemas in the catalog](#downloading-schemas)
-- ⭐️ [Fetch AsyncAPI files from any URL](#fetch-asyncapi-files-by-url)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your AsyncAPI versions](/docs/plugins/asyncapi/features#automatic-versioning)
+- ⭐️ [Allow you to write and persist custom markdown between changes](/docs/plugins/asyncapi/features#persist-markdown)
+- ⭐️ [Display your message schemas in the catalog](/docs/plugins/asyncapi/features#downloading-schemas)
+- ⭐️ [Fetch AsyncAPI files from any URL](/docs/plugins/asyncapi/features#fetch-asyncapi-files-by-url)
 - ⭐️ Ability to download your message schemas and AsyncAPI files (also versioned)
 - ⭐️ Ability to draft services and endpoints in EventCatalog from your AsyncAPI files
 - ⭐️ and more....

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

@@ -53,13 +53,13 @@ Each service in the `services` array requires the following properties:
 | `domain.generateMarkdown` | function | - | Function to override the default markdown generation for the domain. See [Markdown templates](#markdown-templates) for more information. |
 | `messages.generateMarkdown` | function | - | Function to override the default markdown generation for the message. See [Markdown templates](#markdown-templates) for more information. |
 | `messages.id` | object | - | Configure the id of the messages that are generated (for example, set a prefix to all messages that are generated) _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#adding-prefix-to-all-messages) |
-| `messages.id.prefix` | string | - | A prefix value for the message that is generated. For example a message with the id `orderPlaced` with a configured prefix of `hello-` will be `hello-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
-| `messages.id.separator` | string | `-` | The separator to use between the prefix and the message id. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
-| `messages.id.prefixWithServiceId` | boolean | | If true, the service id will be added to the id of the messages that are generated. For example a message with the id `orderPlaced` and the service id `orders-service` will be `orders-service-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
+| `messages.id.prefix` | string | - | A prefix value for the message that is generated. For example a message with the id `orderPlaced` with a configured prefix of `hello-` will be `hello-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#adding-prefix-to-all-messages) |
+| `messages.id.separator` | string | `-` | The separator to use between the prefix and the message id. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#adding-prefix-to-all-messages) |
+| `messages.id.prefixWithServiceId` | boolean | | If true, the service id will be added to the id of the messages that are generated. For example a message with the id `orderPlaced` and the service id `orders-service` will be `orders-service-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#adding-prefix-to-all-messages) |
 | `messages.id.lowerCase` | boolean | false | If true, the message id will be stored in lowercase and the folder will also be lowercased. (e.g `/events/orderplaced/index.mdx) _(Added in v5.0.0)_ |
 | `preserveExistingMessages` | boolean | `true` | Preserve existing message Markdown when the generator runs again. Set to `false` to replace existing Markdown with content generated from the AsyncAPI specification and `messages.generateMarkdown` template. Referenced and external messages are never overwritten. |
 | `saveParsedSpecFile` | boolean | `false` | Parse and save expanded AsyncAPI spec (helpful for files with $refs) |
-| `parseSchemas` | boolean | `true` | If you choose to parse your specification file using the [saveParsedSpecFile](#saveparsedspecfile-saveparsedspecfile) field, you can also opt in or out to have your ,message schemas parsed using the `parseSchemas` field. By default message schemas are parsed, if you want to keep your original schemas you have to set `parseSchemas` to false. | | `parseChannels` | boolean | `false` | Parse and save channels. If you set to true the AsyncAPI channels will also be documented in the catalog. |
+| `parseSchemas` | boolean | `true` | If you choose to parse your specification file using the [saveParsedSpecFile](#optional-configuration-options) field, you can also opt in or out to have your ,message schemas parsed using the `parseSchemas` field. By default message schemas are parsed, if you want to keep your original schemas you have to set `parseSchemas` to false. | | `parseChannels` | boolean | `false` | Parse and save channels. If you set to true the AsyncAPI channels will also be documented in the catalog. |
 | `parseChannels` | boolean | `false` | When setting the value to true the generator will parse and write channels to your EventCatalog. |
 | `writeFilesToRoot` | boolean | `false` | Write AsyncAPI messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure. |
 | `saveParsedSpecFile` | boolean | `true` | By default your AsyncAPI file will render in your catalog as you define it. If you are using $refs, or having issues seeing your AsyncAPI file in your catalog, then you can set this value to true. `saveParsedSpecFile`  is false by default. |

package/dist/docs/plugins/backstage/00-overview.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+title: EventCatalog for Backstage
+description: Add EventCatalog documentation, diagrams, schemas, messages, and flows to Backstage entity pages.
+keywords:
+  - backstage
+  - developer portal
+  - integration
+---
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#licensing" />
+
+The EventCatalog Backstage plugin embeds EventCatalog views in Backstage entity pages. Developers can explore architecture documentation without leaving the software catalog they use for ownership, APIs, dependencies, and operations.
+
+![EventCatalog embedded in a Backstage entity page](/img/integrations/backstage/backstage-eventcatalog.png)
+
+## Choose where to start
+
+- New to the plugin? Follow [Embed EventCatalog in your first Backstage entity](/docs/plugins/backstage/get-started).
+- Adding a dedicated entity tab? Use [Embed EventCatalog as entity tabs](/docs/plugins/backstage/embed-entity-tabs).
+- Adding content to an existing overview? Use [Add EventCatalog cards to an overview page](/docs/plugins/backstage/add-overview-cards).
+- Need exact props or supported components? See the [component reference](/docs/plugins/backstage/components).
+- Upgrading from the legacy resource mapping? Follow [Migrate to entity annotations](/docs/plugins/backstage/migrate-to-annotations).
+
+## Supported views
+
+You can embed:
+
+- resource documentation
+- resource visualizers
+- message discovery tables
+- entity maps
+- the schema explorer
+- the Architecture Graph, focused on a resource at depth 1, 2, or 3
+- the System Context Map overview or a specific system and version
+- a flow visualizer for a specific flow and version
+
+Every page and card accepts `theme="light"` or `theme="dark"`. If you omit `theme`, EventCatalog uses the visitor's saved EventCatalog theme.
+
+## How the integration fits together
+
+The plugin reads the EventCatalog base URL from Backstage configuration and normally reads the EventCatalog resource identity from annotations on the current Backstage entity. It then renders the selected EventCatalog view in an iframe with embed mode enabled.
+
+Read [How EventCatalog embeds work](/docs/plugins/backstage/how-embeds-work) for the mapping, rendering, and sizing model.
+
+## Licensing
+
+The plugin requires an EventCatalog Scale license for commercial use. You can start a 30-day trial in [EventCatalog Cloud](https://eventcatalog.cloud) and follow [Getting a license key for integrations](/docs/development/license-keys/integrations).
+
+For license terms, see the [plugin repository](https://github.com/event-catalog/backstage-plugin-eventcatalog).

package/dist/docs/plugins/backstage/01-get-started.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 2
+sidebar_label: Get started
+title: Embed EventCatalog in your first Backstage entity
+description: Install the EventCatalog Backstage plugin and add resource documentation to an entity page.
+keywords:
+  - backstage
+  - tutorial
+  - installation
+---
+
+In this tutorial, you will connect a Backstage app to an EventCatalog instance and add an EventCatalog documentation tab to a service entity.
+
+You will need:
+
+- a Backstage app with a software catalog entity page
+- an EventCatalog instance that the user's browser can reach
+- an EventCatalog Scale license for commercial use
+
+## 1. Enable the integration in EventCatalog
+
+Add your Scale license key to the `.env` file in the EventCatalog project:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+Build and deploy EventCatalog with this environment variable. For license setup and legacy keys, see [Getting a license key for integrations](/docs/development/license-keys/integrations).
+
+## 2. Install the Backstage plugin
+
+From the root of your Backstage app, install the frontend plugin:
+
+```bash
+yarn add @eventcatalog/backstage-plugin-eventcatalog
+```
+
+## 3. Configure the EventCatalog URL
+
+Add the public base URL of your EventCatalog instance to `app-config.yaml`:
+
+```yaml title="app-config.yaml"
+eventcatalog:
+  URL: https://demo.eventcatalog.dev
+```
+
+Do not add a trailing view path such as `/docs` or `/visualiser`. The plugin builds each embed URL from this base URL.
+
+## 4. Map a Backstage entity
+
+Add EventCatalog annotations to a Backstage catalog entity. This example maps a Backstage component to version `1.0.0` of the `order-service` service in EventCatalog:
+
+```yaml title="catalog-info.yaml"
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: order-service
+  description: Handles customer orders
+  annotations:
+    eventcatalog.dev/id: order-service
+    eventcatalog.dev/version: 1.0.0
+    eventcatalog.dev/collection: services
+spec:
+  type: service
+  lifecycle: production
+  owner: team-orders
+```
+
+The annotation values must match the resource ID, version, and collection in EventCatalog.
+
+## 5. Add an EventCatalog tab
+
+Open the file that defines your catalog entity page, commonly `packages/app/src/components/catalog/EntityPage.tsx`.
+
+Import the page component:
+
+```tsx
+import { EventCatalogDocumentationEntityPage } from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+Add a route inside the `EntityLayout` used for your service entities:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-docs" title="EventCatalog: Docs">
+  <EventCatalogDocumentationEntityPage page="docs" />
+</EntityLayout.Route>
+```
+
+## 6. Check the result
+
+Start Backstage and open the mapped service. Select **EventCatalog: Docs**.
+
+You should see the `order-service` documentation from EventCatalog fill the tab. If you see a mapping message instead, check that `eventcatalog.dev/id` is present and that the entity has been re-ingested by Backstage.
+
+You now have a working EventCatalog embed. Next, [add more entity tabs](/docs/plugins/backstage/embed-entity-tabs) or [place visualizations on the overview page](/docs/plugins/backstage/add-overview-cards).

package/dist/docs/plugins/backstage/02-embed-entity-tabs.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 3
+sidebar_label: Embed entity tabs
+title: Embed EventCatalog as entity tabs
+description: Add documentation, message, schema, map, graph, and flow tabs to Backstage entity pages.
+keywords:
+  - backstage
+  - entity tabs
+  - entity layout
+---
+
+Use full-page components inside `EntityLayout.Route` when you want an EventCatalog view to have its own Backstage entity tab.
+
+## Import the components
+
+Import the general-purpose page component and any dedicated visualization components you need:
+
+```tsx
+import {
+  EventCatalogArchitectureGraphEntityPage,
+  EventCatalogDocumentationEntityPage,
+  EventCatalogFlowEntityPage,
+  EventCatalogSystemContextMapEntityPage,
+} from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+## Add resource views
+
+The documentation, visualizer, discovery table, entity map, and schema explorer use `EventCatalogDocumentationEntityPage`:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-docs" title="EventCatalog: Docs">
+  <EventCatalogDocumentationEntityPage page="docs" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-visualiser" title="EventCatalog: Visualiser">
+  <EventCatalogDocumentationEntityPage page="visualiser" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-messages" title="EventCatalog: Messages">
+  <EventCatalogDocumentationEntityPage page="discover" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-entity-map" title="EventCatalog: Entity Map">
+  <EventCatalogDocumentationEntityPage page="entity-map" />
+</EntityLayout.Route>
+
+<EntityLayout.Route path="/eventcatalog-schema-explorer" title="EventCatalog: Schema Explorer">
+  <EventCatalogDocumentationEntityPage page="schema-explorer" />
+</EntityLayout.Route>
+```
+
+These components use the annotations on the current entity. To show a different resource, pass `id`, `version`, and `collection` explicitly:
+
+```tsx
+<EventCatalogDocumentationEntityPage
+  page="entity-map"
+  id="ordering"
+  version="1.0.0"
+  collection="domains"
+/>
+```
+
+## Add an Architecture Graph
+
+Use `EventCatalogArchitectureGraphEntityPage` to focus the catalog-wide graph on a resource. `depth` accepts `1`, `2`, or `3` and defaults to `2`.
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-architecture" title="EventCatalog: Architecture">
+  <EventCatalogArchitectureGraphEntityPage type="service" depth={2} />
+</EntityLayout.Route>
+```
+
+The resource ID comes from the current entity unless you pass `id`. `type` is the singular alias for `collection`; for example, `type="service"` maps to `services`.
+
+## Add a System Context Map
+
+Omit the props to show the catalog-wide overview:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-system-context" title="EventCatalog: System Context">
+  <EventCatalogSystemContextMapEntityPage />
+</EntityLayout.Route>
+```
+
+To show one system, provide its ID and version:
+
+```tsx
+<EventCatalogSystemContextMapEntityPage
+  system="order-management-system"
+  version="1.0.0"
+/>
+```
+
+On a mapped Backstage `System` entity, the component can read the system ID and version from annotations instead.
+
+## Add a flow
+
+A flow embed requires a flow ID and version:
+
+```tsx
+<EntityLayout.Route path="/eventcatalog-flow" title="EventCatalog: Flow">
+  <EventCatalogFlowEntityPage flow="checkout-saga" version="1.0.0" />
+</EntityLayout.Route>
+```
+
+You can instead annotate a Backstage entity with the flow ID, version, and `flows` collection, then omit the `flow` and `version` props.
+
+For every supported prop and page value, see the [component reference](/docs/plugins/backstage/components).

package/dist/docs/plugins/backstage/03-add-overview-cards.md

@@ -0,0 +1,79 @@
+---
+sidebar_position: 4
+sidebar_label: Add overview cards
+title: Add EventCatalog cards to an overview page
+description: Place EventCatalog diagrams, tables, schemas, and flows in a Backstage overview grid.
+keywords:
+  - backstage
+  - cards
+  - overview
+---
+
+Use the card components to place EventCatalog views alongside existing Backstage cards. The components fill their parent, so give each grid item an explicit height.
+
+## Import the cards
+
+```tsx
+import {
+  EventCatalogEntityArchitectureGraphCard,
+  EventCatalogEntityEntityMapCard,
+  EventCatalogEntityFlowCard,
+  EventCatalogEntityMessageCard,
+  EventCatalogEntitySchemaExplorerCard,
+  EventCatalogEntitySystemContextMapCard,
+  EventCatalogEntityVisualiserCard,
+} from '@eventcatalog/backstage-plugin-eventcatalog';
+```
+
+## Add cards to the overview grid
+
+Add the cards to the `Grid` used by your entity overview. Choose heights that suit each visualization:
+
+```tsx
+const overviewContent = (
+  <Grid container spacing={3} alignItems="stretch">
+    <Grid item xs={12} style={{ height: 700 }}>
+      <EventCatalogEntityFlowCard
+        flow="checkout-saga"
+        version="1.0.0"
+      />
+    </Grid>
+
+    <Grid item xs={12} style={{ height: 800 }}>
+      <EventCatalogEntityArchitectureGraphCard
+        type="service"
+        depth={2}
+      />
+    </Grid>
+
+    <Grid item xs={12} md={6} style={{ height: 600 }}>
+      <EventCatalogEntityVisualiserCard />
+    </Grid>
+
+    <Grid item xs={12} md={6} style={{ height: 600 }}>
+      <EventCatalogEntityMessageCard />
+    </Grid>
+  </Grid>
+);
+```
+
+The resource-oriented cards read the current entity's EventCatalog annotations. Components that select a global or specific view also accept explicit props:
+
+```tsx
+<EventCatalogEntityEntityMapCard
+  id="ordering"
+  version="1.0.0"
+  collection="domains"
+/>
+
+<EventCatalogEntitySystemContextMapCard
+  system="order-management-system"
+  version="1.0.0"
+/>
+
+<EventCatalogEntitySchemaExplorerCard />
+```
+
+To make a card span the whole overview width, use `xs={12}`. To arrange two cards side by side on medium screens, give each item `xs={12} md={6}`.
+
+See [Control embed theme and size](/docs/plugins/backstage/control-theme-and-size) if an iframe does not fill its card.

package/dist/docs/plugins/backstage/04-control-theme-and-size.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 5
+sidebar_label: Theme and sizing
+title: Control an embed's theme and size
+description: Select a light or dark EventCatalog theme and make embeds fill their Backstage containers.
+keywords:
+  - backstage
+  - theme
+  - iframe height
+---
+
+Every EventCatalog page and card component accepts a `theme` prop.
+
+## Select a theme
+
+Set `theme` to `light` or `dark`:
+
+```tsx
+<EventCatalogDocumentationEntityPage page="docs" theme="dark" />
+
+<EventCatalogEntityArchitectureGraphCard
+  type="service"
+  depth={2}
+  theme="light"
+/>
+```
+
+When `theme` is omitted, the embedded page uses the visitor's saved EventCatalog theme. The explicit prop affects that embed; it does not overwrite the visitor's saved preference.
+
+To make every EventCatalog view in a Backstage app consistent, pass the same theme to each page and card component.
+
+## Give cards an explicit height
+
+The plugin iframe uses `height: 100%`, which means its height is inherited from its parent. Set the height on the Backstage grid item or another wrapping element:
+
+```tsx
+<Grid item xs={12} style={{ height: 800 }}>
+  <EventCatalogEntityArchitectureGraphCard
+    type="service"
+    depth={2}
+    theme="dark"
+  />
+</Grid>
+```
+
+Avoid percentage heights unless every ancestor has a defined height. A fixed height, viewport-relative height, or layout-controlled height gives the iframe a concrete area to fill:
+
+```tsx
+<Grid item xs={12} style={{ height: 'calc(100vh - 240px)', minHeight: 600 }}>
+  <EventCatalogEntitySchemaExplorerCard theme="dark" />
+</Grid>
+```
+
+Full-page components automatically fill the height made available by the `EntityLayout.Route`. If a custom route wrapper collapses, give that wrapper an explicit height too.