@eventcatalog/core 4.10.13 → 4.10.14

package/dist/docs/development/customization/05-resource-sidebar.md

@@ -0,0 +1,235 @@
+---
+sidebar_position: 2.5
+keywords:
+- EventCatalog resource sidebar
+- customize sidebar
+- sidebar.json
+sidebar_label: Resource sidebar
+title: Resource sidebar
+description: Define your own sidebar for any resource with a sidebar.json file.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.10.0" />
+
+Every resource in EventCatalog (domains, services, messages, flows, and more) gets a generated sidebar showing its quick reference, architecture, related resources and owners.
+
+![The resource sidebar shown on a system page](./img/resource-sidebar.png)
+
+By default, EventCatalog will generate a sidbar for your resources, but sometimes you may want to customize what is shown here — for example runbooks, guides, external links, or your own grouping of events and services.
+
+To do this, add a `sidebar.json` file next to the resource's `index.mdx`. This file becomes the sidebar for that resource.
+
+```
+domains/
+  Payments/
+    index.mdx
+    sidebar.json        <-- your sidebar for the Payments domain
+```
+
+:::info The file is the sidebar
+When a `sidebar.json` is present it fully replaces the generated sidebar — what you list is what renders, in the order you list it. Nothing is merged in, and anything you don't list isn't shown. Remove the file to get the default sidebar back.
+:::
+
+## Which resources support it?
+
+All of them. A `sidebar.json` can sit next to the `index.mdx` of any **domain, system, service, agent, event, command, query, flow, container (data store), entity, data product or ADR**.
+
+Versioned copies (`versioned/0.0.1/index.mdx`) inherit the resource folder's `sidebar.json` automatically, unless the versioned folder contains its own.
+
+## Quick start
+
+A sidebar is a list of **sections**. A section is either a predefined `$token` (a section EventCatalog generates and keeps up to date for you) or a group you define yourself:
+
+```json title="domains/Payments/sidebar.json"
+{
+  "sections": [
+    // A predefined section, relabelled from "Quick Reference" to "Overview"
+    { "section": "$quick-reference", "title": "Overview" },
+    // Your own group — any Lucide icon name works
+    {
+      "title": "Runbooks",
+      "icon": "Siren",
+      "pages": [
+        // Links to this domain's runbooks/failed-captures documentation page
+        "[[doc|runbooks/failed-captures]]",
+        // A plain link — external links open in a new tab
+        { "title": "Health dashboard", "href": "https://grafana.acme.dev/d/payments" }
+      ]
+    },
+    // Predefined sections, rendered exactly as the default sidebar would
+    "$architecture",
+    "$services",
+    "$owners"
+  ]
+}
+```
+
+This renders: an **Overview** section (the generated Quick Reference, relabelled), your own **Runbooks** group, then the generated **Architecture**, **Services** and **Owners** sections.
+
+## Sections
+
+Each entry in `sections` is one of three shapes:
+
+| Shape | Example | Meaning |
+|-------|---------|---------|
+| Token | `"$architecture"` | A predefined section, rendered exactly as the default sidebar would — and kept up to date as your catalog changes |
+| Adjusted token | `{ "section": "$owners", "title": "Team" }` | A predefined section with a new `title`, `icon` or `collapsed` state |
+| Custom group | `{ "title": "Runbooks", "icon": "Siren", "pages": [...] }` | A group you define. `icon` is any [Lucide](https://lucide.dev) icon name |
+
+A predefined section with nothing behind it (for example `$entities` on a domain with no entities) renders nothing — you can safely list sections that only sometimes have content.
+
+## Pages
+
+Inside a custom group, each entry in `pages` is one of:
+
+| Entry | Example | Renders |
+|-------|---------|---------|
+| Section token | `"$inbound-messages"` | The **items** of a predefined section, spliced into your group — this is how you extend a generated section with your own pages |
+| Resource reference | `"[[service\|payment-api]]"` | The resource, with its own expandable nested sidebar, at its latest version. Messages can pin a version: `"[[event\|payment-captured@1.0.0]]"` — other types always reference the latest |
+| Documentation reference | `"[[doc\|guides/onboarding]]"` | One of this resource's [documentation pages](/docs/development/bring-your-own-documentation/resource-docs/adding-resource-docs), addressed as `<type>/<id>` |
+| Specification reference | `"[[spec\|openapi.yml]]"` | A specification page, with the OpenAPI/AsyncAPI/GraphQL logo and the spec's name |
+| Schema reference | `"[[schema\|payment-captured]]"` | A message's schema page |
+| Link | `{ "title": "Runbook", "href": "https://..." }` | A plain link. External links (any protocol) open in a new tab and show an external-link icon |
+| Nested group | `{ "title": "Internal", "collapsed": true, "pages": [...] }` | A subsection. Groups nest to any depth |
+
+Resource references accept any resource type: `domain`, `system`, `service`, `agent`, `event`, `command`, `query`, `flow`, `container`, `entity`, `channel`, `data-product`, `adr`, `diagram`, `team`, `user`.
+
+### Specification and schema references
+
+Specifications belong to a resource, so a spec reference names the file — and optionally the resource that owns it:
+
+```json
+"[[spec|openapi.yml]]"                              // this resource's own spec
+"[[spec|payment-api/openapi.yml]]"                  // another resource's spec, by id
+"[[spec|service/payment-api/openapi.yml]]"          // type-qualified
+```
+
+Specifications always come from the owner's latest version.
+
+Schema references point at a message's schema page:
+
+```json
+"[[schema|payment-captured]]"                       // latest version
+"[[schema|event/payment-captured@1.0.0]]"           // type-qualified and pinned to a version
+```
+
+### Extending a generated section
+
+Because a `$token` inside `pages` splices in that section's items, extending a generated section is just wrapping it in your own group — placement is list order:
+
+```json
+{
+  "title": "Quick Reference",
+  "icon": "BookOpen",
+  "pages": [
+    // Splices in the generated Quick Reference items (Overview, Changelog, ...)
+    "$quick-reference",
+    // ...followed by your own pages
+    "[[doc|guides/onboarding]]",
+    { "title": "Team Slack", "href": "https://acme.slack.com/archives/payments" }
+  ]
+}
+```
+
+### Link placeholders
+
+Internal links can use `{collection}`, `{id}` and `{version}` placeholders for the resource the sidebar belongs to, so the same file works across versions:
+
+```json
+// On the Payments domain v1.0.0 this renders as
+// "Visualiser (1.0.0)" -> /visualiser/domains/payments/1.0.0
+{ "title": "Visualiser ({version})", "href": "/visualiser/{collection}/{id}/{version}" }
+```
+
+Internal links automatically respect your configured base path.
+
+## Collapsing sections
+
+Any object-form section or group accepts `"collapsed": true | false` as its **initial** state — users can still toggle it, and their choice is remembered:
+
+```json
+// Starts collapsed; users can still expand it and their choice is remembered
+{ "title": "Internal commands", "collapsed": true, "pages": ["[[command|refund-payment]]"] }
+```
+
+Without `collapsed`, groups with more than five items start collapsed and smaller groups start open.
+
+## Predefined sections
+
+Tokens shared by most resource types:
+
+`$quick-reference` · `$documentation` · `$architecture` · `$diagrams` · `$decision-records` · `$owners` · `$code` · `$attachments`
+
+And per resource type:
+
+| Resource | Tokens |
+|----------|--------|
+| Domain | `$api-and-contracts` `$systems` `$subdomains` `$resources` `$services` `$flows` `$entities` `$domain-events` `$external-events` `$resource-groups` `$agents` `$external-integrations` `$data-products` |
+| System | `$resources` `$services` `$flows` `$data-stores` `$entities` |
+| Service / Agent | `$api-and-contracts`* `$resource-groups` `$state-and-persistence` `$entities`* `$outbound-messages` `$inbound-messages` `$channels` `$flows` |
+| Event / Command / Query | `$api-and-contracts` `$producers` `$consumers` `$triggered-by` `$triggers` `$appears-in-flows` |
+| Flow | `$messages` `$services` `$agents` `$subflows` `$data-stores` `$data-products` |
+| Container | `$writes` `$reads` `$appears-in-flows` |
+| Data product | `$inputs` `$outputs` `$data-contracts` `$appears-in-flows` |
+| Entity | `$domains` `$services` |
+| ADR | `$applies-to` `$supersedes` `$superseded-by` `$amends` `$amended-by` `$related-decisions` `$decision-makers` |
+
+\* service only.
+
+Tokens like `$services` that the default sidebar nests inside a "Resources" umbrella render as top-level sections when you use them directly.
+
+## When something doesn't resolve
+
+Mistakes fail fast so your catalog never silently ships a broken sidebar:
+
+- An unknown `$token`, or a `[[doc|…]]`, `[[spec|…]]` or `[[schema|…]]` reference that doesn't resolve **fails the build**, with an error naming the file and listing the valid options.
+- A resource reference (like `[[service|…]]`) to something that doesn't exist renders nothing.
+
+## A complete example
+
+The [demo catalog](https://demo.eventcatalog.dev/docs/domains/catalog/1.0.0) uses resource sidebars throughout. The Catalog domain's sidebar organizes the domain for its consumers — guides first, then the events other teams integrate with:
+
+```json title="domains/Catalog/sidebar.json"
+{
+  "sections": [
+    // Generated Quick Reference, relabelled
+    { "section": "$quick-reference", "title": "Overview" },
+    // The domain's documentation pages, front and center for new consumers
+    {
+      "title": "Guides",
+      "icon": "BookOpen",
+      "pages": [
+        "[[doc|guides/integrating-with-the-catalog]]",
+        "[[doc|guides/product-data-model]]",
+        "[[doc|guides/event-versioning]]"
+      ]
+    },
+    // A curated list of the events other teams subscribe to.
+    // Each renders with its own expandable nested sidebar.
+    {
+      "title": "Integration Events",
+      "icon": "Radio",
+      "pages": ["[[event|product-created]]", "[[event|product-updated]]", "[[event|product-deleted]]"]
+    },
+    // Generated sections — kept up to date as the catalog changes
+    "$architecture",
+    "$systems",
+    "$entities",
+    // Docs mixed with external links in one group
+    {
+      "title": "Runbooks",
+      "icon": "Siren",
+      "pages": [
+        "[[doc|runbooks/on-call]]",
+        "[[doc|runbooks/search-index-lag]]",
+        { "title": "Health dashboard", "href": "https://grafana.acme.dev/d/catalog-overview" }
+      ]
+    },
+    // Out of the way until needed
+    { "title": "Decisions", "icon": "ClipboardList", "collapsed": true, "pages": ["[[adr|adr-001-use-transactional-outbox]]"] },
+    "$owners"
+  ]
+}
+```

package/dist/docs/development/customization/09-embed-eventcatalog.md

@@ -0,0 +1,179 @@
+---
+sidebar_position: 11
+sidebar_label: Embed EventCatalog
+title: Embed EventCatalog in other applications
+description: Bring EventCatalog documentation, diagrams, schemas, messages, and flows into your internal applications.
+keywords:
+  - embed EventCatalog
+  - iframe
+  - developer portal
+  - internal application
+  - Scale
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+You can embed EventCatalog pages in developer portals, internal tools, intranets, and other web applications. Your teams can explore architecture information in the application where they already work while EventCatalog remains the source of the documentation.
+
+Embedding EventCatalog requires an EventCatalog Scale license. See [Getting a license key for EventCatalog Scale](/docs/development/license-keys/plans).
+
+## What you can embed
+
+| Feature | What users can do in the embedded view |
+| --- | --- |
+| Resource documentation | Read the documentation for a domain, system, service, message, flow, team, or another catalog resource. |
+| Resource visualizer | Explore the selected resource and its relationships. |
+| Architecture Graph | Explore the catalog-wide graph or focus it on a resource with a relationship depth of 1, 2, or 3. |
+| System Context Maps | View the catalog-wide system overview or the context surrounding one system. |
+| Entity maps | Explore the entities and relationships associated with a resource. |
+| Flows | Follow the steps, services, and messages in a business or technical flow. |
+| Discovery tables | Browse and filter catalog resources such as services, events, commands, and queries. |
+| Schema explorer | Search schemas, inspect their contents, and see the resources that use them. |
+
+Embedded pages remain interactive. Controls belonging to the selected visualization or table stay available, while EventCatalog's application header and sidebars are removed so they do not compete with the host application's navigation.
+
+## How embedding works
+
+Add `embed=true` to a supported EventCatalog URL and load that URL in an iframe. For example:
+
+```text
+https://catalog.example.com/docs/services/order-service/1.0.0?embed=true
+```
+
+You can also request a light or dark color mode for an embed:
+
+```text
+https://catalog.example.com/docs/services/order-service/1.0.0?embed=true&theme=dark
+```
+
+The requested theme only affects that embedded page. It does not replace the visitor's saved EventCatalog theme.
+
+## Before you embed
+
+- Build and deploy EventCatalog with a valid Scale license.
+- Use an EventCatalog URL that users of the host application can reach from their browsers.
+- If EventCatalog is authenticated, verify that users can authenticate from the embedded context.
+- Give the iframe's parent a defined height. EventCatalog fills the space the host application provides.
+- Review the host application's Content Security Policy and iframe policy if the browser blocks the page.
+
+## Embed a page
+
+### 1. Choose the EventCatalog page
+
+Open the page in EventCatalog and confirm that it contains the content you want users to see. Prefer an explicit resource version so the embedded URL is stable.
+
+For example, a service visualizer may have this URL:
+
+```text
+https://catalog.example.com/visualiser/services/order-service/1.0.0
+```
+
+### 2. Enable embed mode
+
+Add `embed=true` to the query string:
+
+```text
+https://catalog.example.com/visualiser/services/order-service/1.0.0?embed=true
+```
+
+Use `&embed=true` instead when the URL already has query parameters.
+
+### 3. Add the iframe
+
+Give the container a concrete height and let the iframe fill it:
+
+```html
+<div style="height: 700px; width: 100%;">
+  <iframe
+    src="https://catalog.example.com/visualiser/services/order-service/1.0.0?embed=true"
+    title="Order service architecture"
+    loading="lazy"
+    style="border: 0; display: block; height: 100%; width: 100%;"
+  ></iframe>
+</div>
+```
+
+`height: 100%` only works when the iframe's ancestors have a defined height. Use a fixed, viewport-relative, or layout-controlled height in the host application.
+
+### 4. Select a theme
+
+Add `theme=light` or `theme=dark` to force the embedded page's color mode:
+
+```html
+<iframe
+  src="https://catalog.example.com/schemas/explorer?embed=true&theme=dark"
+  title="Schema explorer"
+></iframe>
+```
+
+If you omit `theme`, EventCatalog uses the visitor's saved EventCatalog preference or their system preference.
+
+## Embed URL reference
+
+Replace `https://catalog.example.com` with the URL of your deployed catalog.
+
+| Feature | URL pattern |
+| --- | --- |
+| Resource documentation | `/docs/{collection}/{id}/{version}?embed=true` |
+| Resource visualizer | `/visualiser/{collection}/{id}/{version}?embed=true` |
+| Discovery table | `/discover/{collection}?embed=true` |
+| Entity map | `/visualiser/{collection}/{id}/{version}/entity-map?embed=true` |
+| Data dependency view | `/visualiser/{collection}/{id}/{version}/data?embed=true` |
+| Schema explorer | `/schemas/explorer?embed=true` |
+| Schema details | `/schemas/{type}/{id}/{version}?embed=true` |
+| Architecture Graph | `/visualiser/graph?embed=true` |
+| System Context Map overview | `/visualiser/system-context-map?embed=true` |
+| System-specific context map | `/visualiser/systems/{id}/{version}/context?embed=true` |
+| Flow visualizer | `/visualiser/flows/{id}/{version}?embed=true` |
+
+Collections use their plural route names, such as `domains`, `systems`, `services`, `events`, `commands`, `queries`, `flows`, and `entities`. Schema detail pages support message types such as `events`, `commands`, and `queries`, as well as data product contracts.
+
+### Focus the Architecture Graph
+
+Use `focus={collection}/{id}` to select the initial resource and `depth` to choose how many relationship hops are visible. `depth` accepts `1`, `2`, or `3`.
+
+```text
+https://catalog.example.com/visualiser/graph?embed=true&focus=services/order-service&depth=2
+```
+
+The Architecture Graph must be enabled in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  visualiser: {
+    architectureGraph: {
+      enabled: true,
+    },
+  },
+};
+```
+
+## Troubleshooting
+
+### EventCatalog shows a license overlay
+
+Confirm that the deployed catalog was built or started with a valid Scale license. Add the key to the EventCatalog project's environment:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+Then rebuild and redeploy the catalog. See [Getting a license key for EventCatalog Scale](/docs/development/license-keys/plans).
+
+### Navigation is still visible
+
+Confirm that the URL contains `embed=true`, including the exact lowercase value `true`.
+
+### The iframe is blank or blocked
+
+Open the iframe URL directly in the same browser. Confirm that it is reachable and that the user can authenticate. Then check the browser console for Content Security Policy, mixed-content, or iframe permission errors from either application.
+
+### The content does not fill the available height
+
+Set an explicit height on the iframe's parent and keep the iframe at `height: 100%`. Check every ancestor if you use a percentage height.
+
+## Backstage
+
+If your host application is Backstage, use the [EventCatalog Backstage plugin](/docs/plugins/backstage/overview). It supplies React components, resolves EventCatalog resources from Backstage entity annotations, and constructs the embed URLs for you.

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

@@ -7,6 +7,6 @@
     "type": "generated-index",
     "slug": "development/customization",
     "title": "Customization Documentation",
-    "description": "Learn how to customize EventCatalog."
+    "description": "Customize EventCatalog and embed its documentation and visualizations in other applications."
   }
 }

package/dist/docs/development/deployment/build-and-deploy.md

@@ -32,6 +32,10 @@ This will output one directory
 
 - `dist` - Your EventCatalog as Static HTML
 
+### Link validation
+
+Static builds check internal links and anchors and report warnings by default. See [link validation](/docs/development/deployment/link-validation) to fail builds on broken links, ignore destinations, or disable the check.
+
 ### Passing custom options
 
 <AddedIn version="2.16.5" />

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

@@ -22,7 +22,7 @@ By default EventCatalog will build a static website.
 
 Here are some guides and places you can host static content
 
-- [Host with Docker](#hosting-with-docker)
+- [Host with Docker](#hosting-static-website-with-docker)
 - [Deploy to NextJS](https://nextjs.org/docs/deployment)
 - [Host in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
 

package/dist/docs/development/deployment/link-validation.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 5
+sidebar_label: Link validation
+title: Link validation
+description: Catch broken links and anchors before they reach production
+---
+
+After a static build, EventCatalog scans every generated HTML page and reports internal links and anchors that don't resolve. This catches typos in [resource references](/docs/development/components/resource-references), renamed pages, and moved custom docs before they ship.
+
+## What gets checked
+
+- Links between pages rendered by your catalog, including the sidebar navigation.
+- Anchors (`#section`) on the destination page, so a link to a heading that no longer exists is caught too.
+- Links are resolved against your [`base`](/docs/api/config#base) path, so this works the same whether your catalog is hosted at the root or a subpath.
+
+Only links on the same origin and under the catalog's `base` path are checked. Set [`homepageLink`](/docs/api/config#homepageLink) to your deployed URL so absolute links to your own catalog are recognized as internal. External links and non-HTTP links such as `mailto:` are skipped.
+
+Links to files in the build output are checked for existence, but fragments in non-HTML files such as PDFs are not validated. Links created only by client-side JavaScript are not checked, except for sidebar navigation.
+
+:::info
+Link validation only runs after a [static build](/docs/development/deployment/build-and-deploy). It's skipped when running in [SSR mode](/docs/development/deployment/build-ssr-mode), since pages are rendered on demand rather than generated up front.
+:::
+
+## Configure the check
+
+By default, broken links and anchors are logged as warnings and the build still succeeds.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    onBrokenLinks: 'warn',
+    onBrokenAnchors: 'warn',
+  },
+};
+```
+
+Set either option to `error` to fail the build instead, or `ignore` to skip that check completely.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    onBrokenLinks: 'error',
+    onBrokenAnchors: 'ignore',
+  },
+};
+```
+
+Turn the whole feature off by setting `linkValidation` to `false`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: false,
+};
+```
+
+## Ignore known destinations
+
+Some links can't be verified during the build, such as pages generated by a separate process. Use `ignore` with glob patterns for the destination paths. See [`linkValidation.ignore`](/docs/api/config#linkvalidationignore) for how paths are matched.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    ignore: ['/api/**', '/docs/legacy/*'],
+  },
+};
+```
+
+## Run in CI
+
+Set both checks to `error` in CI to fail the build on broken links or anchors. Keep `warn` locally if you want the build to succeed while you fix them.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  linkValidation: {
+    onBrokenLinks: process.env.CI ? 'error' : 'warn',
+    onBrokenAnchors: process.env.CI ? 'error' : 'warn',
+  },
+};
+```
+
+```yaml title=".github/workflows/build-catalog.yml"
+name: Build catalog
+on:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm run build
+        env:
+          CI: true
+```
+
+When a check is set to `error`, broken destinations fail the build. Diagnostics group references by destination and show up to five source pages per destination. For user/team and event/command/query mixups, EventCatalog suggests an alternative only when that destination exists in the build.
+
+## Related
+
+- [`eventcatalog.config.js` reference](/docs/api/config#linkValidation) for the full list of options
+- [Resource references](/docs/development/components/resource-references) for linking to catalog resources

package/dist/docs/development/developer-tools/eventcatalog-linter/00-overview.md

@@ -0,0 +1,76 @@
+---
+sidebar_position: 1
+slug: /development/developer-tools/eventcatalog-linter
+keywords:
+- EventCatalog linter
+- schema validation
+- reference validation
+- CI/CD
+- quality assurance
+sidebar_label: Overview
+title: EventCatalog Linter
+description: Catch broken references, typos, misplaced files and missing metadata in your EventCatalog before they reach a build or a reader.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The EventCatalog Linter is a command-line tool that checks your catalog for the mistakes EventCatalog itself would otherwise ignore or only surface at build time: a service that `sends` an event that doesn't exist, a typo like `owner:` instead of `owners:`, a `schemaPath` that points at nothing, or a file saved in a folder EventCatalog never reads.
+
+Run it locally while you write documentation, or in CI so every pull request is checked.
+
+```bash
+npx @eventcatalog/linter
+```
+
+```
+services/order-service/index.mdx
+   6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+   9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+  14:1 ⚠ warning Resource should have a markdown description (body content) beyond just frontmatter [description] (best-practices/description-required)
+
+✖ 3 problems (2 errors, 1 warning) in 1 file
+  178 files checked
+```
+
+## What it checks
+
+| Area | Examples |
+|------|----------|
+| **Frontmatter schemas** | Required fields, field types, version formats, unknown or misspelled keys |
+| **References** | Owners, messages, services, domains, channels, containers, flow steps and entity relationships point at resources (and versions) that exist |
+| **Files** | `schemaPath`, `schemas[]`, `specifications`, data product contracts and `public/` icons resolve to real files |
+| **Catalog structure** | Duplicate ids, markdown files in places EventCatalog won't load |
+| **Documentation quality** | Summaries, owners, body content and message schemas are present |
+| **Versioning** | References to deprecated resources |
+
+Every finding comes with a `line:column` position, the rule that produced it, and — where the linter can work it out — a suggestion for the fix.
+
+## Where to go next
+
+- **[Set up the linter](./01-setup.md)** — a guided walk-through from the first run to a CI check. Start here if you haven't used the linter before.
+- **[How-to guides](/docs/development/developer-tools/eventcatalog-linter/how-to)** — recipes for specific jobs: [configure rules](./how-to/01-configure-rules.md), [run in CI](./how-to/02-run-in-ci.md), [allow custom frontmatter](./how-to/03-use-custom-frontmatter.md), [reference resources from other catalogs](./how-to/04-reference-external-catalogs.md), [fix common problems](./how-to/05-fix-common-problems.md).
+- **[Reference](/docs/development/developer-tools/eventcatalog-linter/reference)** — every [CLI option](./reference/01-cli.md), the [configuration file](./reference/02-configuration.md), [all rules](./reference/03-rules.md) with their messages and options, [version formats](./reference/04-versions.md) and the [files the linter scans](./reference/05-supported-resources.md).
+
+## What's new
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+The latest release focuses on catching the mistakes people actually make and pointing at exactly where they are:
+
+- **Line and column numbers** on every finding, so terminals and editors can jump straight to the problem.
+- **Unknown frontmatter keys** are flagged with "did you mean" suggestions ([`schema/unknown-field`](./reference/03-rules.md#schemaunknown-field)). EventCatalog fails the build on these; the linter now catches them first.
+- **Misplaced files** — `events/OrderCreated.mdx` instead of `events/OrderCreated/index.mdx`, `event/` instead of `events/`, users saved as folders — are reported with the intended location ([`structure/unrecognised-file`](./reference/03-rules.md#structureunrecognised-file)).
+- **Broken file references** — `schemaPath`, specifications, contracts and icons that don't exist ([`refs/file-exists`](./reference/03-rules.md#refsfile-exists)).
+- **Clearer reference errors**: "this resource doesn't exist — did you mean `OrderCreated`?" is now distinct from "this resource exists, but not at version `2.1.0` — available: `2.0.0`, `1.0.0`".
+- **Version formats match EventCatalog**: `1`, `1.2`, `v1` and `V2` are accepted everywhere EventCatalog accepts them.
+- `eventcatalog-linter --init` scaffolds a fully commented config; `--quiet`, `--max-warnings` and `--no-color` were added; progress output stays out of CI logs; the summary reports how many files were actually checked.
+
+Read the [rules reference](./reference/03-rules.md) for the full list, or the [original announcement](/blog/eventcatalog-linter) for the background.
+
+## Supported resources
+
+The linter understands every resource type EventCatalog does: domains and subdomains, systems, services, events, commands, queries, channels, flows, entities, agents, containers, data products, diagrams, ADRs, users and teams — including versioned copies under `versioned/` and content pulled in through federation. See [Supported resources](./reference/05-supported-resources.md) for the exact folders and file names it scans.
+
+## Issues?
+
+If you have any issues or feedback, please open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord server](https://eventcatalog.dev/discord).