@eventcatalog/core 4.12.0-beta.9 → 4.12.1

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.12.0-beta.9";
+var version = "4.12.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-YOIPWS7L.js";
-import "../chunk-UIHG2TPV.js";
+} from "../chunk-HH6GPY4H.js";
+import "../chunk-HHZFKWX7.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -176,7 +176,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.12.0-beta.9";
+var version = "4.12.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-4S47JELQ.js";
+} from "../chunk-UWSBZYF5.js";
+import "../chunk-HH6GPY4H.js";
 import "../chunk-ZAZHAVKB.js";
-import "../chunk-YOIPWS7L.js";
-import "../chunk-UIHG2TPV.js";
+import "../chunk-HHZFKWX7.js";
 import "../chunk-RFIXKATC.js";
 export {
   log_build_default as default

package/dist/{chunk-GNFKUOXD.js → chunk-DZZDBFUM.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-UIHG2TPV.js";
+} from "./chunk-HHZFKWX7.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-K3DWGBGQ.js → chunk-EVXNBTRA.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-GNFKUOXD.js";
+} from "./chunk-DZZDBFUM.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-YOIPWS7L.js → chunk-HH6GPY4H.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-UIHG2TPV.js";
+} from "./chunk-HHZFKWX7.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-UIHG2TPV.js → chunk-HHZFKWX7.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.12.0-beta.9";
+var version = "4.12.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-4S47JELQ.js → chunk-UWSBZYF5.js}

@@ -1,11 +1,11 @@
+import {
+  raiseEvent
+} from "./chunk-HH6GPY4H.js";
 import {
   countResources,
   hashCatalogContent,
   serializeCounts
 } from "./chunk-ZAZHAVKB.js";
-import {
-  raiseEvent
-} from "./chunk-YOIPWS7L.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "4.12.0-beta.9";
+var version = "4.12.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-UIHG2TPV.js";
+} from "./chunk-HHZFKWX7.js";
 export {
   VERSION
 };

package/dist/docs/development/01-getting-started/develop-and-build.md

@@ -24,6 +24,24 @@ npm run dev
 ```
 If all goes well, EventCatalog will now be serving your project on http://localhost:3000/. Visit that link in your browser and see your new site!
 
+### Clear the development cache
+
+<AddedIn version="4.12.0" />
+
+EventCatalog runs directly in your project and keeps generated files, such as content caches, types, and runtime metadata, in the `.astro/` folder.
+
+If the development server shows stale content, start it with `--force-recreate`. This clears and regenerates the whole `.astro/` folder.
+
+```bash
+npx eventcatalog dev --force-recreate
+```
+
+Keep `.astro/` in your `.gitignore` and `.dockerignore` files. New catalogs created with `create-eventcatalog` include it in both.
+
+:::info Upgrading from an older version?
+Before 4.12, EventCatalog copied itself into a `.eventcatalog-core/` folder in your project. EventCatalog no longer creates this folder. Once any older EventCatalog processes have stopped, you can delete it. `eventcatalog dev` and `eventcatalog build` tell you when the folder is safe to delete.
+:::
+
 ## Build and preview your catalog
 
 To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command in your terminal:

package/dist/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md

@@ -52,6 +52,10 @@ _Example of installing the OpenAI model:_
 npm install @ai-sdk/openai
 ```
 
+:::info AI SDK version
+From EventCatalog 4.12, the assistant uses [AI SDK v7](https://ai-sdk.dev/). Install a provider package that supports AI SDK v7, for example `@ai-sdk/openai@^4`. If you have [custom tools](/docs/development/ask-your-architecture/eventcatalog-assistant/bring-your-own-tools) that use AI SDK v6 APIs, update them to the v7 equivalents.
+:::
+
 #### Configuring `eventcatalog.chat.js`
 
 This file will provide the model and any model configuration to EventCatalog.

package/dist/docs/development/components/components/27-code-group.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 7.1
+keywords:
+  - components
+  - code group
+  - code examples
+sidebar_label: CodeGroup
+title: CodeGroup
+description: Show the same code example in several languages or files
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.11.0"/>
+
+The `<CodeGroup />` component groups several fenced code blocks into one panel. Readers switch between them with tabs or a dropdown, and copy the one they need.
+
+Use it when the same example exists in more than one language, or when an example is split across several files.
+
+![CodeGroup in dropdown mode, showing a TypeScript example with a language picker for TypeScript, Python, Java, C#, and Go](./img/code-group-dropdown.png)
+
+**Example**
+
+Wrap your code blocks in `<CodeGroup>`. The text after the language becomes the label for each block.
+
+````mdx title="/events/OrderCreated/index.mdx"
+<CodeGroup>
+
+```ts publish.ts
+await client.publish('OrderCreated', order);
+```
+
+```python publish.py
+client.publish("OrderCreated", order)
+```
+
+</CodeGroup>
+````
+
+Leave a blank line after the opening tag and before the closing tag, so the code blocks are parsed as Markdown.
+
+### Output
+
+![CodeGroup with TypeScript and Python tabs, shown next to an explanation using Columns](./img/columns-code-group.png)
+
+### Labels
+
+Each code block needs a label. EventCatalog picks it in this order:
+
+1. A `title` in the code fence, for example ` ```ts title="publish.ts" `
+1. The first word after the language, for example ` ```ts publish.ts `
+1. The language, for example `ts`
+
+EventCatalog also shows an icon for the language of each block, for example TypeScript, Python, Java, Go, C#, or JSON.
+
+When a reader picks a block, every other code group on the page with a block of the same label switches too. If a page has several examples that each include `publish.py`, choosing Python once shows Python everywhere.
+
+### Use a dropdown
+
+Tabs work well for two or three blocks. For more, add `dropdown` to show a language picker instead.
+
+````mdx title="/events/OrderCreated/index.mdx"
+<CodeGroup dropdown>
+
+```javascript publish-order.js
+await client.publish("OrderCreated", order);
+```
+
+```python publish_order.py
+client.publish("OrderCreated", order)
+```
+
+```java PublishOrder.java
+client.publish("OrderCreated", order);
+```
+
+```csharp PublishOrder.cs
+await client.PublishAsync("OrderCreated", order);
+```
+
+</CodeGroup>
+````
+
+### Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `dropdown` | `boolean` | `false` | Show a dropdown to switch between code blocks instead of tabs. |
+| `className` | `string` | | Extra CSS classes for the group. |
+
+### Support
+
+The `<CodeGroup />` component is supported in domains, systems, services, all messages, flows, changelogs, custom documentation pages, and [message usage examples](/docs/development/guides/resources/messages/add-usage-examples).
+
+Pair it with [`<Columns />`](/docs/development/components/components/columns) to show code next to the text that explains it.

package/dist/docs/development/components/components/28-columns.md

@@ -0,0 +1,115 @@
+---
+sidebar_position: 7.2
+keywords:
+  - components
+  - columns
+  - layout
+sidebar_label: Columns
+title: Columns
+description: Place content side by side in your EventCatalog pages
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.11.0"/>
+
+The `<Columns />` component places content side by side. Each `<Column />` inside it is one column.
+
+A common use is to put an explanation on the left and the code it describes on the right.
+
+**Example**
+
+````mdx title="/events/OrderCreated/index.mdx"
+<Columns cols={2}>
+
+  <Column>
+
+    ## Publish a review
+
+    Publish the event after the review is stored.
+
+  </Column>
+
+  <Column>
+
+    <CodeGroup>
+
+      ```ts publish.ts
+      await client.publish('ReviewSubmitted', review);
+      ```
+
+      ```python publish.py
+      client.publish("ReviewSubmitted", review)
+      ```
+
+    </CodeGroup>
+
+  </Column>
+
+</Columns>
+````
+
+Leave a blank line after each opening tag and before each closing tag, so the content inside is parsed as Markdown.
+
+### Output
+
+![Two columns, with an explanation on the left and a code group on the right](./img/columns-code-group.png)
+
+### Set the column widths
+
+By default, every column has the same width. Use `ratio` to change that. The ratio needs one number per column.
+
+```mdx title="/events/OrderCreated/index.mdx"
+<Columns cols={2} ratio="2:1">
+
+  <Column>
+
+    This column is twice as wide as the next one.
+
+  </Column>
+
+  <Column>
+
+    This column is narrower.
+
+  </Column>
+
+</Columns>
+```
+
+If the ratio does not match the number of columns, EventCatalog uses equal widths.
+
+### Keep a column in view
+
+Add `sticky` to a column to keep it in view while the reader scrolls past a longer column next to it. This is useful for long explanations next to a short code sample.
+
+```mdx
+<Column sticky>
+
+  ...
+
+</Column>
+```
+
+On narrow screens, columns stack on top of each other and `sticky` has no effect.
+
+### Props
+
+**`<Columns />`**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `cols` | `number` | `2` | Number of columns, from 1 to 4. |
+| `ratio` | `string` | | Relative column widths, for example `"2:1"` or `"1:2:1"`. |
+| `className` | `string` | | Extra CSS classes for the columns. |
+
+**`<Column />`**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `sticky` | `boolean` | `false` | Keep the column in view while the page scrolls. |
+| `className` | `string` | | Extra CSS classes for the column. |
+
+### Support
+
+The `<Columns />` component is supported in domains, systems, services, all messages, flows, changelogs, custom documentation pages, and [message usage examples](/docs/development/guides/resources/messages/add-usage-examples).

package/dist/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md

@@ -10,6 +10,7 @@ description: Add a custom Astro page to your EventCatalog.
 ---
 
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
+import AddedIn from '@site/src/components/MDX/AddedIn';
 
 This guide shows you how to add a custom page to your catalog.
 
@@ -172,6 +173,26 @@ const { id } = Astro.params;
 
 This page is available at `/custom/reports/:id`, for example `/custom/reports/orders`.
 
+## Render a full-width page
+
+<AddedIn version="4.12.0" />
+
+Custom pages get the same page padding as built-in pages. If your page needs the full width, for example a dashboard, pass `fullWidth` to the layout.
+
+```js title="pages/dashboard.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Dashboard" fullWidth>
+  <div class="h-full w-full">
+    <!-- Your full-width content -->
+  </div>
+</Layout>
+```
+
+See the [`Layout` props](/docs/development/customization/custom-pages-and-api-routes/reference#layout-props) for all options.
+
 ## Learn more
 
 Custom pages follow Astro's routing model. See the [Astro pages documentation](https://docs.astro.build/en/basics/astro-pages/) if you want to go deeper.

package/dist/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md

@@ -103,6 +103,30 @@ Use these aliases in custom pages.
 | `@catalog/utils` | Stable catalog data helpers such as `getServices`, `getDomains`, and `getEvents`. |
 | `@catalog/components/*` | Components from your catalog's top-level `components` directory. |
 
+## `Layout` props
+
+`@catalog/layouts/Layout.astro` accepts these props.
+
+```js title="pages/reports.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Service reports" description="Operational views built from catalog data." sidebar={false}>
+  <h1>Service reports</h1>
+</Layout>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | | Page title. Required. |
+| `description` | `string` | | Page description used in the page metadata. |
+| `sidebar` | `boolean` | `true` | Show the resource sidebar (domains, services, messages). |
+| `showHeader` | `boolean` | `true` | Show the EventCatalog header (search and navigation). |
+| `fullWidth` | `boolean` | `false` | Render content edge-to-edge without EventCatalog's page padding. Added in 4.12.0. |
+
+By default, custom pages get the same page padding and theme text color as built-in pages, so they read well in light and dark mode. Set `fullWidth` when your page controls its own layout, for example a dashboard or an embedded tool. Full-width pages still inherit the theme text color.
+
 ## `@catalog/utils`
 
 Use `@catalog/utils` to read catalog resources from custom pages and API routes.

package/dist/docs/development/deployment/hosting-options.md

@@ -102,6 +102,14 @@ Then you can run the server with:
 docker run -p 3000:3000 eventcatalog-server
 ```
 
+:::warning Your `.env` file is included in the server image
+
+`COPY . .` copies your `.env` file into the image, so EventCatalog can read your license key and other keys (for example `OPENAI_API_KEY`) during the build and when the server runs.
+
+Anyone who can pull the image can read these keys. Only push the image to a private registry, and do not share it publicly.
+
+:::
+
 :::info "Why do I need a server to run EventCatalog?"
 
 Some features of EventCatalog require a server to run (e.g. [EventCatalog Chat](/features/ai-assistant) and [EventCatalog Authentication](/docs/development/authentication/introduction)).

package/dist/docs/development/guides/resources/messages/09-add-usage-examples.md

@@ -13,16 +13,16 @@ sidebar_position: 7
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-EventCatalog lets you attach example payloads to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
+EventCatalog lets you attach examples to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
 in your architecture and provide them with real examples.
 
-Examples appear in the Schema Explorer under a **Usage Examples** tab alongside the schema, properties, and changelog tabs.
+Examples appear in the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer) under an **Examples** tab alongside the schema, properties, and version tabs.
 
-![Example](./imgs/examples.png)
+![Examples tab in the Schema Explorer showing a written example next to a code group with JavaScript, Python, Java, and C# snippets](./imgs/examples.png)
 
 ### Add examples
 
-Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, and more.
+Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, Markdown, MDX, and more.
 
 <ProjectTree
   items={[
@@ -54,7 +54,99 @@ Create an `examples/` folder inside your message directory and drop in any examp
   ]}
 />
 
-The **Usage Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+The **Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+
+All examples for a message are shown on the same tab, one after another, ordered by file path.
+
+### Write examples in Markdown or MDX
+
+<AddedIn version="4.11.0" />
+
+Raw payloads show consumers the shape of a message, but not how to use it. Write your examples in Markdown or MDX to explain the scenario, call out important fields, and show code in more than one language.
+
+<ProjectTree
+  items={[
+    {
+      name: 'OrderCreated',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: 'index.mdx' },
+        { name: 'schema.json' },
+        {
+          name: 'examples',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Markdown and MDX examples are rendered as documentation, not as source code. Use [`<Columns />`](/docs/development/components/components/columns) to put the explanation next to the code, and [`<CodeGroup />`](/docs/development/components/components/code-group) to show the same example in several languages.
+
+:::info Other components
+On the schema page (`/schemas/{type}/{id}/{version}`), MDX examples can use any EventCatalog [component](/docs/components/list). The preview panel on the `/schemas/explorer` list only supports `<Columns />`, `<Column />`, and `<CodeGroup />`, and shows MDX examples that use other components as source.
+:::
+
+````mdx title="events/OrderCreated/examples/index.mdx"
+---
+summary: Publish OrderCreated from checkout.
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## Publish a single-item order
+
+Publish an order containing one T-shirt after checkout succeeds.
+
+### Payload details
+
+- `orderId` identifies the order; `customerId` identifies the customer.
+- `total` uses integer minor units; `currency` is `GBP`.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```javascript publish-order.js
+await client.publish("OrderCreated", {
+  orderId: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  total: 4999,
+  currency: "GBP",
+});
+```
+
+```python publish_order.py
+client.publish("OrderCreated", {
+    "orderId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+    "total": 4999,
+    "currency": "GBP",
+})
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+````
+
+Markdown and MDX examples support these frontmatter fields. Both are optional.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `title` | `string` | Title for the example. When omitted, EventCatalog uses the first level-one heading, then the file name. |
+| `summary` | `string` | Short description shown above the example. |
+
+:::tip
+You can put every example in a single `examples/index.mdx` file, or split them across several files. Use a horizontal rule (`---`) between examples in the same file to separate them.
+:::
 
 ### Organise with subfolders
 
@@ -105,13 +197,15 @@ international-order.json:
   summary: An order with international shipping and customs information.
 ```
 
-All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension as the title.
+All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension.
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `name` | `string` | Display name shown in the examples list |
-| `summary` | `string` | Short description shown below the name |
-| `usage` | `string` | How-to-run snippet shown below the code block |
+| `name` | `string` | Display name for the example |
+| `summary` | `string` | Short description shown above the example |
+| `usage` | `string` | How-to-run snippet shown below the example |
+
+For Markdown and MDX examples, you can use frontmatter instead of the config file. Values in `examples.config.yaml` take precedence.
 
 ### Use the SDK