@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/dist/docs/development/guides/resources/messages/10-reference.md

@@ -223,9 +223,12 @@ Versioned messages use:
 | `/docs/events/{event-id}/{version}` | Event documentation page. |
 | `/docs/commands/{command-id}/{version}` | Command documentation page. |
 | `/docs/queries/{query-id}/{version}` | Query documentation page. |
-| `/visualiser/events/{event-id}/{version}` | Event resource diagram. |
-| `/visualiser/commands/{command-id}/{version}` | Command resource diagram. |
-| `/visualiser/queries/{query-id}/{version}` | Query resource diagram. |
+| `/docs/events/{event-id}/{version}/resources` | Event [Resources page](/docs/development/guides/resources/messages/what-are-messages#resources-page). |
+| `/docs/commands/{command-id}/{version}/resources` | Command [Resources page](/docs/development/guides/resources/messages/what-are-messages#resources-page). |
+| `/docs/queries/{query-id}/{version}/resources` | Query [Resources page](/docs/development/guides/resources/messages/what-are-messages#resources-page). |
+| `/visualiser/events/{event-id}/{version}` | Event diagram (**Diagram** in the sidebar). |
+| `/visualiser/commands/{command-id}/{version}` | Command diagram (**Diagram** in the sidebar). |
+| `/visualiser/queries/{query-id}/{version}` | Query diagram (**Diagram** in the sidebar). |
 
 ## Required fields
 

package/dist/docs/development/guides/resources/schemas/04-explore-schemas/01-schema-explorer.md

@@ -59,7 +59,7 @@ Each schema is split into tabs. EventCatalog only shows a tab when there is some
 | **Flows** | The [flows](/docs/development/guides/resources/flows/introduction) the message is part of. |
 | **Versions** | Every version of the schema, with a side-by-side comparison. |
 | **Details** | Schema metadata: format, version, file, source, and owners. |
-| **API** | API access to the schema (EventCatalog Scale). |
+| **API** | API access to the schema. |
 
 ##### Link to a tab
 
@@ -114,4 +114,4 @@ The **Details** tab shows the schema name, format, message type, version, file,
 
 ##### API Access
 
-For EventCatalog Scale users, you can get API (GET) access to your schemas for mocking or testing. See [Schema API](/docs/development/guides/resources/schemas/schema-api).
+You can get API (GET) access to your schemas for mocking or testing. See [Schema API](/docs/development/guides/resources/schemas/schema-api).

package/dist/docs/development/guides/resources/schemas/04-explore-schemas/02-fields-explorer.md

@@ -11,7 +11,6 @@ description: Browse, search, and trace schema fields across all messages in your
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 :::info SSR required
 The Fields Explorer requires EventCatalog to run in SSR (server-side rendering) mode. It is not available in static builds.
@@ -19,10 +18,8 @@ The Fields Explorer requires EventCatalog to run in SSR (server-side rendering)
 
 <iframe width="100%" height="415" src="https://www.youtube.com/embed/PQIBATgtuKs?si=TagMKL49ZD_G_HYE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-
 The Fields Explorer gives you a catalog-wide view of every schema field across all your events, commands, and queries (supporting AVRO, JSON, and Proto). Search and filter fields by name, format, or message type, then click any field to trace exactly which services produce and consume it.
 
-
 ![Field Explorer](../img/field-search.png)
 
 ## Get started
@@ -64,8 +61,6 @@ Each row in the table represents a single field in a specific message schema.
 
 ## Trace field lineage
 
-<PlanBanner plan="Scale" />
-
 Clicking any field row opens a full-screen **Field Traceability** panel. This panel shows a node graph with three layers:
 
 1. **Producer services** -- services that publish the message containing this field
@@ -76,12 +71,8 @@ The right-hand panel lists the same information in a collapsible format and lets
 
 ![Field Explorer](../img/field-search-graph.png)
 
-_[If you want to try this feature you can get a 30-day free trial of EventCatalog Scale](https://eventcatalog.cloud)_
-
 ## Detect type conflicts
 
-<PlanBanner plan="Scale" />
-
 When the same field path appears in multiple messages with different data types, the Fields Explorer surfaces a **type conflict**.
 
 ![Field Explorer](../img/type-conflicts-row.png)

package/dist/docs/development/guides/resources/schemas/05-schema-api.md

@@ -8,9 +8,6 @@ description: Get API (GET) access to your schemas for mocking or testing
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
-
-<PlanBanner plan="Scale" />
 
 EventCatalog provides an API to get access to your schemas and specifications.
 

package/dist/docs/development/guides/resources/schemas/06-schema-mcp.md

@@ -8,9 +8,6 @@ description: Get access to your schemas for your MCP clients (e.g Cursor, Windsu
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import PlanBanner from '@site/src/components/MDX/PlanBanner';
-
-<PlanBanner plan="Scale" />
 
 The [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) allows you to get access to your documentation and context in your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc).
 
@@ -19,3 +16,14 @@ Your documented schemas for your Events, Queries, Commands and Services can be a
 This allows you to ask questions about your schemas, get schema information for your services and messages, directly in your code editor or LLM.
 
 To get started, you can follow the guide to [get started with the EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started).
+
+### Show schemas to users
+
+<AddedIn version="5.0.0" />
+
+The MCP server has two tools for schemas:
+
+- `showResource` with `view: "schema"` shows a schema to the user. In MCP clients that support MCP Apps (for example Claude, ChatGPT and VS Code), the schema opens in the same viewer as the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer), with a **Schema** tab and a **Properties** tab for JSON Schema, Avro and Protobuf. Other clients get the schema code.
+- `getSchemaForResource` returns the schemas and specifications (OpenAPI, AsyncAPI, GraphQL) of a resource for the agent to read, for example to generate code.
+
+Ask things like "show me the schema for OrderCreated" and the agent calls `showResource`. See [interactive diagrams and schemas](/docs/development/ask-your-architecture/mcp-server/getting-started#interactive-diagrams-and-schemas) for the parameters.

package/dist/docs/development/guides/resources/services/04-add-resources-to-services/03-add-entities-to-services.md

@@ -34,7 +34,7 @@ Your service markdown...
 
 <AddedIn version="3.25.1" />
 
-When a service has entities assigned, EventCatalog generates a dedicated **Entity Map** page in the visualizer at `/visualiser/services/{id}/{version}/entity-map`. A link to this view appears automatically in the service sidebar under the visualizer section.
+When a service has entities assigned, EventCatalog generates a dedicated **Entity Diagram** page in the visualizer at `/visualiser/services/{id}/{version}/entity-map`. An **Entity Diagram** link to this view appears automatically in the **Architecture** section of the service sidebar.
 
 The entity map shows each entity as a node and draws edges between entities that reference one another using the `references` field in their properties. This gives you a quick overview of how the domain model is structured inside a service.
 

package/dist/docs/development/guides/resources/services/05-resources-page.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog services
+- Service resources
+- Resources page
+sidebar_label: Service resources page
+title: Service resources page
+description: See every message, entity, data store, flow, and decision record connected to a service.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.0.0" />
+
+Every service gets a **Resources** page that lists everything connected to it in one table. Open it from **Quick Reference** > **Resources** in the service's sidebar, or go to `/docs/services/{service-id}/{version}/resources`.
+
+![Order Service Resources page with Inbound and Outbound filters, type filters, a Relationship column and pagination](./img/service-resources-page.png)
+
+## What the page lists
+
+The page lists the resources your service is connected to:
+
+| Resource | Where it comes from | Relationship |
+|----------|---------------------|--------------|
+| Events, commands and queries | The service's `sends` and `receives` ([add messages to services](/docs/development/guides/resources/services/add-resources-to-services/add-messages-to-services)) | **Sends**, **Receives** or **Sends & receives** |
+| Entities | The service's `entities` ([add entities to services](/docs/development/guides/resources/services/add-resources-to-services/add-entities-to-services)) | **Owns** |
+| Data stores | The service's `writesTo` and `readsFrom` ([add data stores to services](/docs/development/guides/resources/services/add-resources-to-services/add-data-stores-to-services)) | **Writes to**, **Reads from** or **Reads & writes** |
+| Flows | The service's `flows`, and any flow with a step that points at the service ([flows](/docs/development/guides/resources/flows/introduction)) | **Appears in** |
+| Decision records | Any ADR whose `appliesTo` includes the service ([add ADRs to resources](/docs/development/guides/resources/adrs/linking-resources)) | **Governed by** |
+
+The **Resources** link only shows in the sidebar when the service has at least one resource to list.
+
+## Find resources in the table
+
+- **Relationship column**: shows how each resource connects to the service, for example **Sends**, **Receives** or **Reads from**.
+- **Inbound** and **Outbound** filters: show only what comes into the service (messages it receives, data stores it reads from) or what goes out of it (messages it sends, data stores it writes to). These filters only show when the service has connections in both directions.
+- **Type filters**: show only one or more kinds of resource, such as **Events**, **Commands** or **Data Stores**. A filter only shows for types the service has.
+- **Filter...**: search by name, id or summary.
+- **Sorting**: click the **Name**, **Type**, **Relationship** or **Version** column header to sort.
+- **Pagination**: page through long lists and choose how many rows to show with **Per page**.
+
+## Row actions
+
+Each row has a **...** menu with quick actions:
+
+- **View documentation**: open the resource's docs page.
+- **View in visualiser**: open the resource in the visualiser (when the visualiser is enabled and the resource has a diagram).
+- **View schema**: open the message's schema page (when the message has a schema).
+- **Add to favorites**: pin the resource to your favorites. Choose **Remove from favorites** to unpin it.

package/dist/docs/development/guides/resources/services/08-reference.md

@@ -39,7 +39,8 @@ Versioned services use:
 | Route | Description |
 |-------|-------------|
 | `/docs/services/{service-id}/{version}` | Service documentation page. |
-| `/visualiser/services/{service-id}/{version}` | Service resource diagram. |
+| `/docs/services/{service-id}/{version}/resources` | Service [Resources page](/docs/development/guides/resources/services/resources-page). |
+| `/visualiser/services/{service-id}/{version}` | Service diagram (**Diagram** in the sidebar). |
 
 ## Required fields
 

package/dist/docs/development/guides/systems/01-introduction.md

@@ -10,7 +10,7 @@ description: What are systems? Why are they useful in EventCatalog?
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 A system is a collection of resources that work together to perform a function.
 

package/dist/docs/development/guides/systems/02-create-system.md

@@ -11,7 +11,7 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 import PromptBox from '@site/src/components/MDX/PromptBox';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 A system is a collection of resources that work together to perform a function.
 
@@ -123,5 +123,5 @@ The Cart System owns the shopping cart. It accepts commands to add and remove it
 - [Add resources to the system](/docs/development/guides/systems/add-resources-to-systems)
 - [Model relationships and actors](/docs/development/guides/systems/model-relationships-and-actors)
 - [Add systems to domains](/docs/development/guides/domains/add-resources-to-domains/add-systems-to-domains)
-- [Visualize systems with context maps](/docs/development/guides/systems/system-context-maps)
+- [Visualize systems with diagrams](/docs/development/guides/systems/system-context-maps)
 - [Review the systems reference](/docs/development/guides/systems/reference)

package/dist/docs/development/guides/systems/03-add-resources-to-systems.md

@@ -11,7 +11,7 @@ description: Add services, flows, entities, and data stores to systems.
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 In EventCatalog, systems can directly reference:
 
@@ -134,24 +134,50 @@ You can also define resources inside the system folder to keep related architect
 
 This structure makes the system the entry point for the resources that make up that capability.
 
-## Show the resource diagram
-
-Add `<NodeGraph />` to the system page to show the resources inside the system.
-
+## Show the system's resources on its page
 
+Add `<NodeGraph />` to the system page to show the services and data stores inside the system, and the messages between them.
 
 ```md title="/domains/Shopping/systems/cart-system/index.mdx"
-## Resource Diagram
+## Architecture
 
 <NodeGraph />
 ```
 
-![Product Catalog System resource diagram](./img/product-catalog-system-resource-map.png)
+![Product Catalog System showing its services, messages, and data stores](./img/product-catalog-system-resource-map.png)
 
-You can also open the resource diagram directly:
+Each system also has a **Diagram** page, linked from the **Architecture** section of the system sidebar. Level 2 (**L2**) of the Diagram shows the services and data stores inside the system, and level 3 (**L3**) adds the messages and channels:
 
 ```txt
-/visualiser/systems/{system-id}/{version}
+/visualiser/systems/{system-id}/{version}?level=2
 ```
 
+Learn more in [System diagrams](/docs/development/guides/systems/system-context-maps).
+
+## Resources page
+
+Every system with resources gets a **Resources** page that lists them in one table. Open it from **Quick Reference** > **Resources** in the system's sidebar, or go to:
+
+```txt
+/docs/systems/{system-id}/{version}/resources
+```
+
+The page lists the resources attached directly to the system:
+
+| Resource | Where it comes from | Relationship |
+|----------|---------------------|--------------|
+| Services | The system's [`services`](/docs/development/guides/systems/reference#services) | **Contains** |
+| Flows | The system's [`flows`](/docs/development/guides/systems/reference#flows) | **Contains** |
+| Entities | The system's [`entities`](/docs/development/guides/systems/reference#entities) | **Owns** |
+| Data stores | The system's [`containers`](/docs/development/guides/systems/reference#containers) | **Contains** |
+| Decision records | Any ADR whose `appliesTo` includes the system ([add ADRs to resources](/docs/development/guides/resources/adrs/linking-resources)) | **Governed by** |
+
+Messages are not listed on a system's Resources page. To see them, open the Resources page of a service in the system.
+
+The table has the same filters, sorting and row actions as the service Resources page. See [Service resources page](/docs/development/guides/resources/services/resources-page).
+
+:::info Changed in EventCatalog v5
+The sidebar link was called **System Resources** and is now **Resources**. The page now lists decision records and has a **Relationship** column. The system architecture overview page (`/architecture/systems/{system-id}/{version}`) is removed. Old links redirect to the Resources page, or to the system's docs page when it has nothing to list.
+:::
+
 For the complete list of supported fields, see the [systems reference](/docs/development/guides/systems/reference).

package/dist/docs/development/guides/systems/04-model-relationships-and-actors.md

@@ -11,7 +11,7 @@ description: Model relationships between systems and the actors that interact wi
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 Systems can describe how they relate to other systems and which people, roles, or external participants interact with them.
 
@@ -77,10 +77,12 @@ Add `<ContextDiagram />` to a system page to show the system in context with rel
 <ContextDiagram />
 ```
 
-You can also open the context diagram directly:
+The context diagram is also level 1 (**L1**) of the system's **Diagram** page, linked from the **Architecture** section of the system sidebar:
 
 ```txt
-/visualiser/systems/{system-id}/{version}/context
+/visualiser/systems/{system-id}/{version}?level=1
 ```
 
+Learn more in [System diagrams](/docs/development/guides/systems/system-context-maps).
+
 For the complete relationship and actor fields, see the [systems reference](/docs/development/guides/systems/reference).

package/dist/docs/development/guides/systems/05-system-context-maps.md

@@ -2,24 +2,25 @@
 sidebar_position: 5
 keywords:
 - EventCatalog systems
-- System context map
+- System context diagram
+- System diagram
 - Architecture visualizer
-sidebar_label: System context maps
-title: System context maps
-description: Visualize systems from high-level context maps down to detailed resource maps.
+sidebar_label: System diagrams
+title: System diagrams
+description: Visualize systems from the System Context Diagram down to the services, messages, and data stores inside one system.
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
-System context maps help teams understand how systems fit together across an architecture.
+System diagrams help teams understand how systems fit together across an architecture.
 
-They give users a high-level view of all systems, the actors that interact with them, and the relationships between systems. From there, users can drill into a specific system to see the resources that make it up, including APIs, services, messages, data stores, and flows.
+They give users a high-level view of all systems, the actors that interact with them, and the relationships between systems. From there, users can drill into a specific system to see the resources that make it up, including services, messages, channels, and data stores.
 
-## Start with the system context map
+## Start with the System Context Diagram
 
-The global system context map shows your systems and how they relate to each other.
+The global System Context Diagram shows your systems and how they relate to each other.
 
 Use this view when you want to answer questions like:
 
@@ -28,9 +29,9 @@ Use this view when you want to answer questions like:
 - Which people or roles interact with these systems?
 - Where should I drill in for more detail?
 
-![System context map showing systems, actors, and relationships](./img/system-context-map.png)
+![System Context Diagram showing systems, actors, and relationships](./img/system-context-map.png)
 
-You can open the global system context map at:
+When your catalog has systems, a **System Context Diagram** link appears in the **Top level diagrams** section of the sidebar. You can also open it at:
 
 ```txt
 /visualiser/system-context-map
@@ -38,31 +39,47 @@ You can open the global system context map at:
 
 ## Drill into a system
 
-After users understand the high-level context, they can click into a system and view its resource diagram.
+<AddedIn version="5.0.0" />
 
-The resource diagram shows the detailed architecture inside that system. For example, a payment processing system can show the APIs, workers, commands, events, and data stores that work together to process payments.
-
-![System resource map showing APIs, messages, services, and data stores inside a system](./img/system-resource-map.png)
-
-You can open a system resource diagram at:
+Every system has a **Diagram** page. Open it from **Diagram** in the **Architecture** section of the system sidebar, or at:
 
 ```txt
 /visualiser/systems/{system-id}/{version}
 ```
 
-For example:
+The Diagram shows the system at three levels of detail. Switch levels with **L1**, **L2** and **L3** in the canvas toolbar at the bottom of the diagram.
+
+| Level | What it shows |
+|-------|---------------|
+| **L1** | The system context: the system with the systems it has relationships with and its actors. The system you are viewing is marked **Viewing**. |
+| **L2** | The context stays, and the system expands into its services and data stores and how they connect. Its relationships and actors connect to the expanded system. |
+| **L3** | Adds the messages and channels. |
+
+![Payment Processing System diagram at level 1, showing the system and the external systems it has relationships with](./img/system-diagram-l1.png)
+
+![Payment Processing System diagram at level 2, with the system expanded into its services and data store](./img/system-diagram-l2.png)
+
+The page opens at level 1. The level is kept in the URL, so a shared link opens at the same level. Use `?level=` to open a level directly:
 
 ```txt
-/visualiser/systems/search-system/1.0.0
+/visualiser/systems/payment-processing-system/1.0.0?level=2
 ```
 
+The canvas toolbar and menu also let you simulate messages, hide messages or channels, and hide resource types from the legend. See [NodeGraph interactive controls](/docs/development/components/components/nodegraph#interactive-controls).
+
+:::info Changed in EventCatalog v5
+The system's **Context Diagram** and **Resource Diagram** pages are replaced by the single **Diagram** page. The old Context Diagram route (`/visualiser/systems/{system-id}/{version}/context`) redirects to level 1.
+
+Layouts saved in dev mode for a system's context diagram carry over to level 1. Layouts saved for a system's old Resource Diagram don't carry over to levels 2 and 3. Save the layout again if you need it.
+:::
+
 ## High-level to detailed architecture
 
 The goal of systems is to let users move through your architecture at the right level of detail:
 
-- Start with a high-level context map to understand the systems and relationships.
-- Select a system to understand what it owns and depends on.
-- Drill into the resources inside that system to inspect APIs, messages, services, data stores, and flows.
+- Start with the System Context Diagram to understand the systems and relationships.
+- Select a system and open its Diagram at level 1 to see what it depends on.
+- Switch to levels 2 and 3 to inspect the services, data stores, messages, and channels inside that system.
 
 This gives teams a path from architecture overview to implementation detail without forcing every user to start at the lowest level.
 

package/dist/docs/development/guides/systems/06-reference.md

@@ -10,7 +10,7 @@ description: Frontmatter fields, paths, and routes for systems in EventCatalog.
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="4.0" />
+<AddedIn version="4.0.0" />
 
 This page lists the fields, paths, and routes supported by systems.
 
@@ -40,9 +40,9 @@ Versioned systems use the same versioning pattern as other EventCatalog resource
 | Route | Description |
 |-------|-------------|
 | `/docs/systems/{system-id}/{version}` | System documentation page. |
-| `/visualiser/systems/{system-id}/{version}` | Resource diagram for one system. |
-| `/visualiser/systems/{system-id}/{version}/context` | Context diagram for one system. |
-| `/visualiser/system-context-map` | Global system context map. |
+| `/docs/systems/{system-id}/{version}/resources` | [Resources page](/docs/development/guides/systems/add-resources-to-systems#resources-page) listing the resources attached to the system. |
+| `/visualiser/systems/{system-id}/{version}` | [Diagram](/docs/development/guides/systems/system-context-maps) for one system, with levels L1 to L3. Add `?level=1`, `?level=2` or `?level=3` to open a level directly. |
+| `/visualiser/system-context-map` | Global System Context Diagram. |
 
 ## Required fields
 

package/dist/docs/development/license/01-license-file.md

@@ -0,0 +1,151 @@
+---
+sidebar_position: 1
+keywords:
+- license
+- license.jwt
+- EC_LICENSE
+- trial
+- offline license
+sidebar_label: License file
+title: License file
+description: Where to put your license.jwt file, how EventCatalog verifies it, and how EventCatalog shows your license and trial status.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.0.0" />
+
+From v5, EventCatalog is licensed under the Business Source License 1.1 and every feature is included (on a paid plan, federation is Enterprise only). Your license is a signed file called `license.jwt`. EventCatalog reads it to show who the catalog is licensed to and when the license expires.
+
+This page covers how the file works. To find out whether you need a commercial license, read the [licensing FAQ](/license-faq). For prices, see [pricing](/pricing).
+
+:::info Using v4 license keys?
+
+License keys such as `EVENTCATALOG_SCALE_LICENSE_KEY` are covered in [License Keys (v4)](/docs/development/license-keys/overview).
+
+:::
+
+## Get a license file
+
+Get your `license.jwt` from [EventCatalog Cloud](https://eventcatalog.cloud). Free users confirm their eligibility there, and commercial customers get a file with their license. See [license keys in the FAQ](/license-faq#keys).
+
+One file covers your whole organization. You don't need a file per catalog or per environment.
+
+## Add the file to your catalog
+
+Put `license.jwt` in the root of your catalog, next to `eventcatalog.config.js`.
+
+```txt
+my-catalog/
+├── domains/
+├── services/
+├── eventcatalog.config.js
+└── license.jwt
+```
+
+To keep the file somewhere else, set `EC_LICENSE` to the path of the file. `EC_LICENSE` is a file path, not the contents of the file.
+
+```bash title=".env"
+EC_LICENSE=/etc/secrets/eventcatalog/license.jwt
+```
+
+EventCatalog loads `.env` before it checks the license, so you can set `EC_LICENSE` there or in your shell.
+
+### Use the file in CI/CD
+
+You can commit `license.jwt` with your catalog. If you prefer not to, store its contents as a CI secret, write it to a file during the job, and point `EC_LICENSE` at that file:
+
+```bash
+# LICENSE_JWT is a CI secret that holds the contents of license.jwt
+echo "$LICENSE_JWT" > "$RUNNER_TEMP/license.jwt"
+export EC_LICENSE="$RUNNER_TEMP/license.jwt"
+
+npx eventcatalog build
+```
+
+## How the file is verified
+
+EventCatalog verifies the file offline, against a public key built into EventCatalog. It checks the signature, the issuer, the audience, and the dates the license is valid from and until.
+
+There are no calls home: the license works air-gapped, and nothing about your catalog is sent to EventCatalog to verify it.
+
+When you change the file, EventCatalog verifies it again.
+
+## License status in the terminal
+
+`eventcatalog dev` and `eventcatalog build` print the catalog's license status when they start.
+
+With a valid license, they show who it's licensed to and when it expires:
+
+```txt
+   ╭────── EventCatalog Commercial License ──────╮
+   │                                             │
+   │   Licensed to Acme Ltd                      │
+   │   Valid until Oct 1, 2027 (359 days left)   │
+   │                                             │
+   ╰─────────────────────────────────────────────╯
+```
+
+| Status | What the terminal shows |
+| --- | --- |
+| Valid license | A green **EventCatalog Commercial License** box with who it's licensed to and the expiry date. |
+| Expires in fewer than 30 days | A yellow box with the days left and a link to [eventcatalog.cloud](https://eventcatalog.cloud) to renew it. |
+| Expired license | A yellow **EventCatalog License Expired** box with the date it expired, a link to renew it, and the trial status. |
+| Invalid license | A yellow **EventCatalog license** box with the reason, the trial status, and a link to the licensing FAQ. |
+| No license | An **EventCatalog trial** box with the days left of the trial and when it ends. |
+
+A license is invalid when it can't be verified, for example when:
+
+- the file is empty
+- it is not valid yet
+- its signature is invalid
+- it was not issued by EventCatalog
+- it has no expiry date
+
+## License status in the catalog
+
+### Header badge
+
+While you run `eventcatalog dev`, the header shows a badge for your license or trial. The badge never appears in built or served catalogs.
+
+| Status | Badge | Links to |
+| --- | --- | --- |
+| No license | **Trial · N days left**, counting down the trial | [Licensing FAQ](/license-faq) |
+| No license, trial over | **Trial ended** | [Licensing FAQ](/license-faq) |
+| Valid license, 30 or more days left | No badge | |
+| Valid license, fewer than 30 days left | **License · N days left** | Settings > License |
+| Expired license | **License expired** | Settings > License |
+
+### Settings > License
+
+**Settings > License** (`/settings/license`) shows the catalog's license. For a valid license it lists:
+
+- **Licensed to**
+- **License ID**
+- **Issued**
+- **Expires**
+- **Time left**
+
+When the license has fewer than 30 days left, or has expired, the page shows a callout with a **Renew license** button that opens [EventCatalog Cloud](https://eventcatalog.cloud). When the file can't be verified, the page shows the reason.
+
+Without a valid license, the page also shows the trial: its length, when it started, when it ends and the time left.
+
+In a static build, the page shows the license as it was when you built the catalog. The days left are counted in the browser, so they stay current.
+
+## The trial
+
+Without a valid license, EventCatalog counts down a trial, starting from when you first ran your catalog.
+
+The trial countdown in EventCatalog is a reminder. The terms of the evaluation, and what to do when it ends, are in the [licensing FAQ](/license-faq#production).
+
+## When a trial or license ends
+
+Your catalog keeps building and running. EventCatalog never fails a build, or turns features off, because a trial ended or a license expired. It shows reminders in the terminal, in the dev header and on Settings > License.
+
+To renew a license, get a new `license.jwt` from [EventCatalog Cloud](https://eventcatalog.cloud) and replace the file.
+
+## v4 license keys
+
+EventCatalog checks for a `license.jwt` first. If there isn't a valid one, it still recognizes a Scale or Starter license key (`EVENTCATALOG_SCALE_LICENSE_KEY` or `EVENTCATALOG_STARTER_LICENSE_KEY`). With one of those keys, EventCatalog shows no trial, and Settings > License shows the plan as active.
+
+These keys are verified online, as they were in v4. See [License Keys (v4)](/docs/development/license-keys/overview).

package/dist/docs/development/license/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "License",
+  "position": 10.5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/license",
+    "title": "License",
+    "description": "How EventCatalog v5 reads and verifies your license file, and how the trial works."
+  }
+}

package/dist/docs/development/license-keys/_category_.json

@@ -1,12 +1,12 @@
 {
-  "label": "License Keys",
+  "label": "License Keys (v4)",
   "position": 11,
   "collapsible": true,
   "collapsed": true,
   "link": {
     "type": "generated-index",
     "slug": "development/license-keys",
-    "title": "License Keys",
-    "description": "How to get and use license keys for EventCatalog Scale, Enterprise, and integrations (OpenAPI, AsyncAPI, and more)."
+    "title": "License Keys (v4)",
+    "description": "How license keys worked in EventCatalog v4 and earlier. From v5, everything is included: see the licensing FAQ."
   }
 }