@eventcatalog/core 4.10.13 → 4.10.15

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/05-fix-common-problems.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 5
+sidebar_label: Fix common problems
+title: Fix common linter findings
+description: What the most frequent linter messages mean and the quickest way to resolve each one.
+---
+
+Use this guide as a lookup table when the linter reports something and you want the fix, not the theory. Findings are grouped by rule; every rule is documented in full in the [rules reference](../reference/rules).
+
+## "Unknown property … Did you mean …?"
+
+```
+6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+```
+
+A frontmatter key isn't part of the schema — almost always a typo. Rename it to the suggestion. If it's a deliberate custom field, prefix it with `x-` (see [Allow custom frontmatter](./use-custom-frontmatter)).
+
+If the message says the key "is valid on service resources, but not on event resources", you've copied frontmatter from one resource type to another; remove the key or use the equivalent for that type (for example events use `producers`/`consumers`, services use `sends`/`receives`).
+
+## "… is not recognised as an EventCatalog resource and will be ignored"
+
+```
+1:1 ⚠ warning File "events/OrderCreated.mdx" is not recognised … Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+```
+
+The file is in a place EventCatalog never reads. Move it to the suggested path. The common shapes:
+
+| You have | You need |
+|----------|----------|
+| `events/OrderCreated.mdx` | `events/OrderCreated/index.mdx` |
+| `event/…`, `Services/…`, `comands/…` | `events/…`, `services/…`, `commands/…` |
+| `users/john/index.mdx` | `users/john.mdx` (users and teams are flat files) |
+| `events/OrderCreated/versioned/index.mdx` | `events/OrderCreated/versioned/1.0.0/index.mdx` |
+| `services/order-service/notes.mdx` | `services/order-service/docs/notes.mdx` (only `index.mdx` is a resource) |
+
+See [Supported resources](../reference/supported-resources) for every folder the linter scans.
+
+## "Referenced … does not exist"
+
+```
+9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+```
+
+The id doesn't match any resource of the expected type. Check for:
+
+- **A typo** — the message suggests the closest id.
+- **The wrong type** — "`payment-service` exists as a service, not a event/command/query" means the id is real but you referenced it from a field that expects a different type.
+- **A resource from another catalog** — declare it in `dependencies` (see [Reference external catalogs](./reference-external-catalogs)).
+- **A resource the linter can't see** — it may be misplaced (look for an accompanying `structure/unrecognised-file` warning) or matched by an `ignorePatterns` entry.
+
+## "… does not have a version matching …"
+
+```
+9:14 ✖ error Referenced event "OrderCreated" does not have a version matching "3.0.0". Available versions: 2.0.0, 1.0.0 [sends[0]] (refs/valid-version-range)
+```
+
+The resource exists, but not at that version. Either pick one of the listed versions, use a range (`^2.0.0`, `2.x`) or `latest`, or add the missing version under `versioned/`. Version formats and matching are described in the [versions reference](../reference/versions).
+
+If the message says the reference "has an invalid version reference", the value isn't a version, range or `latest` at all — for example `two` or `version-1`.
+
+## "Referenced schema file … does not exist"
+
+```
+7:13 ✖ error Referenced schema file "schema.json" does not exist (looked for "events/OrderCreated/schema.json") [schemaPath] (refs/file-exists)
+```
+
+The path in `schemaPath`, `schemas[]`, `specifications` or a data product contract doesn't resolve to a file. Paths are relative to the resource's own folder — so a versioned copy under `versioned/1.0.0/` needs its own `schema.json` next to it. The "looked for" path shows exactly where the linter checked.
+
+For `styles.icon`, paths starting with `/` are checked against the catalog's `public/` folder. If your static assets live elsewhere, set `['error', { publicDir: 'static' }]` or disable icon checks with `{ icons: false }`.
+
+## "version: Expected string, but received undefined"
+
+```
+2:1 ✖ error version: Expected string, but received undefined [version] (schema/valid-type)
+```
+
+A required field is missing — here `version`. Add it. The same rule reports fields of the wrong type, such as `owners: platform-team` (a string) instead of a list.
+
+## "Invalid semantic version format"
+
+```
+4:10 ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+```
+
+Use a format EventCatalog understands: semver (`1.2.3`, `1.0.0-beta`), a number-like version (`1`, `1.2`, `v1`, `V2`) or `latest`. Values like `one`, `1.0.0.0` or `version-1` are rejected.
+
+## "… has no producer and no consumer"
+
+```
+2:5 ⚠ warning event "OrderCreated" has no producer and no consumer [id] (refs/orphan-messages)
+```
+
+Nothing sends or receives the message, so it won't appear in any visualiser. Add it to a service's `sends` or `receives`, list `producers`/`consumers` on the message itself, or — if it's intentionally standalone — set the rule to `'off'` for that folder using an override.
+
+## "At least one owner is required" / "Summary is required"
+
+Add `owners:` (a list of user or team ids) or `summary:` to the resource. If a resource type genuinely shouldn't need these in your catalog, relax the rule for that folder:
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  overrides: [{ files: ['**/containers/**'], rules: { 'best-practices/owner-required': 'off' } }],
+};
+```
+
+## "Duplicate … also defined in …"
+
+Two files declare the same type, `id` and `version`. Usually one is a leftover copy or a versioned file whose `version` wasn't updated — delete one or correct the version.
+
+## "Parse error: …"
+
+```
+5:14 ✖ error Parse error: unexpected end of the stream within a flow collection (@eventcatalog/parse-error)
+```
+
+The frontmatter isn't valid YAML. The position points at the failing token; look for unbalanced brackets, a missing space after a colon, or inconsistent indentation.
+
+## Related
+
+- [Rules reference](../reference/rules)
+- [Configure rules](./configure-rules)

package/dist/docs/development/developer-tools/eventcatalog-linter/how-to/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "How-to guides",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/developer-tools/eventcatalog-linter/how-to",
+    "title": "Linter how-to guides",
+    "description": "Task-focused guides for configuring rules, running the linter in CI, and fixing what it reports."
+  }
+}

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/01-cli.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 1
+sidebar_label: CLI
+title: Linter CLI reference
+description: Command, options, exit codes, output format and environment behaviour of eventcatalog-linter.
+---
+
+## Usage
+
+```
+eventcatalog-linter [options] [directory]
+```
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `directory` | The catalog to lint — the folder containing `eventcatalog.config.js` | `.` |
+
+Run it with `npx @eventcatalog/linter`, or install `@eventcatalog/linter` and use the `eventcatalog-linter` binary.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Show verbose output |
+| `-q, --quiet` | Report errors only. Warnings are dropped from the output and from the counts |
+| `--fail-on-warning` | Exit with code 1 when any warning is reported. Equivalent to `--max-warnings 0` |
+| `--max-warnings <number>` | Exit with code 1 when more than `<number>` warnings are reported. Must be a non-negative integer |
+| `--no-color` | Disable coloured output |
+| `--init` | Write a commented `.eventcatalogrc.js` to the catalog directory and exit without linting. See [configuration](./configuration#scaffold-a-configuration-file) |
+| `--force` | With `--init`, overwrite an existing `.eventcatalogrc.js` |
+| `-V, --version` | Print the linter version |
+| `-h, --help` | Print help |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No errors. Warnings may have been reported, provided they don't exceed `--max-warnings` |
+| `1` | At least one error was reported, warnings exceeded `--max-warnings` / `--fail-on-warning` was set, an option was invalid, or the linter itself failed |
+
+`--init` exits `0` after writing the file and `1` if the file already exists (without `--force`).
+
+## Output
+
+Findings are grouped by file and sorted by position:
+
+```
+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
+
+✖ 3 problems (2 errors, 1 warning) in 1 file
+  178 files checked, 3 files ignored
+```
+
+| Part | Meaning |
+|------|---------|
+| `6:1` | 1-based line and column of the finding. Keys are reported at the key; references at the value; missing fields at the nearest parent (line 2 for a missing top-level field); body-content findings at the first line after the frontmatter; YAML parse errors at the failing token |
+| `✖ error` / `⚠ warning` | Severity after applying your configuration |
+| `[owner]` | The frontmatter field path, including array indexes (`sends[0].to[1]`) |
+| `(schema/unknown-field)` | The rule name. Parse failures use `(@eventcatalog/parse-error)` |
+| `in 1 file` | Number of files with at least one finding |
+| `178 files checked` | Number of files scanned and validated, after `ignorePatterns` |
+| `3 files ignored` | Number of recognised files skipped by `ignorePatterns` (omitted when zero) |
+
+When nothing is found:
+
+```
+✔ No problems found!
+  178 files checked
+```
+
+When the directory contains no recognisable catalog files, the linter prints `⚠ No EventCatalog files found` and exits `0`.
+
+## Progress output and terminals
+
+A progress spinner is written to **stderr** while the linter runs. It is shown only when stderr is an interactive terminal, the `CI` environment variable is not set, and `TERM` is not `dumb`. In pipelines and when piping output, nothing is written to stderr, so logs contain only findings.
+
+Colour follows [chalk](https://github.com/chalk/chalk) conventions: `--no-color`, `NO_COLOR=1` or `FORCE_COLOR=0` disable it; `FORCE_COLOR=1` enables it in non-TTY output.
+
+## Files the linter reads
+
+| File | Purpose |
+|------|---------|
+| `.eventcatalogrc.js` | Rule configuration. Optional; see [configuration](./configuration) |
+| `eventcatalog.config.js` | Read for `dependencies` so references to external resources resolve. Optional |
+| Resource `index.md` / `index.mdx` files | See [supported resources](./supported-resources) |
+| Files referenced from frontmatter | `schemaPath`, `schemas[]`, `specifications`, contracts and `public/` icons are checked for existence by [`refs/file-exists`](./rules#refsfile-exists) |
+
+The linter never modifies your catalog.
+
+## Programmatic use
+
+The package exports the pieces the CLI is built from — `scanCatalogFiles`, `parseAllFiles`, `validateCatalog`, `validateUnrecognisedFiles`, `attachLocations`, `loadConfig`, `applyRuleSeverity`, `reportErrors`, the rule registry (`RULES`) and version helpers — for use from your own scripts:
+
+```ts
+import { scanCatalogFiles, parseAllFiles, validateCatalog, loadConfig } from '@eventcatalog/linter';
+
+const rootDir = process.cwd();
+const config = loadConfig(rootDir);
+const files = await scanCatalogFiles(rootDir);
+const { parsed } = await parseAllFiles(files);
+const findings = validateCatalog(parsed, undefined, config);
+```
+
+The public API is not yet frozen; expect it to be consolidated into a single `lint()` entry point in a future release.

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/02-configuration.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 2
+sidebar_label: Configuration
+title: Linter configuration reference
+description: The shape of .eventcatalogrc.js — rules, options, ignore patterns, overrides — and how it merges with the defaults.
+---
+
+The linter looks for `.eventcatalogrc.js` in the directory it lints. The file is optional; without it every rule runs at its default severity.
+
+## Scaffold a configuration file
+
+```bash
+npx @eventcatalog/linter --init          # writes .eventcatalogrc.js
+npx @eventcatalog/linter --init --force  # overwrites an existing one
+```
+
+The generated file lists every rule grouped by category, with a description, its default severity and an example of its options. It uses `export default` when the catalog's `package.json` has `"type": "module"` and `module.exports` otherwise.
+
+## Shape
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    '<rule-name>': '<severity>',
+    '<rule-name>': ['<severity>', { /* options */ }],
+  },
+  ignorePatterns: ['<glob>', '<glob>'],
+  overrides: [
+    {
+      files: ['<glob>', '<glob>'],
+      rules: {
+        '<rule-name>': '<severity>',
+        '<rule-name>': ['<severity>', { /* options */ }],
+      },
+    },
+  ],
+};
+```
+
+Every top-level key is optional.
+
+### `rules`
+
+An object keyed by rule name. Rule names are listed in the [rules reference](./rules).
+
+| Value | Effect |
+|-------|--------|
+| `'error'` | Report and fail the run |
+| `'warn'` | Report; fail only with `--fail-on-warning` / `--max-warnings` |
+| `'off'` | Don't check |
+| `[severity, options]` | As above, with rule-specific options. See each rule for its options |
+
+Unknown rule names are ignored silently.
+
+### `ignorePatterns`
+
+Glob patterns, matched against each file's path relative to the catalog root (forward slashes). Matching files are not validated, not counted, and not reported by `structure/unrecognised-file`.
+
+`dependencies/**` is always ignored in addition to what you list.
+
+Supported syntax is deliberately simple: `*` matches within a path segment and `**` matches across segments. A pattern beginning with `**/` needs at least one leading folder to match, so prefer `drafts/**` to `**/drafts/**` for a top-level folder.
+
+### `overrides`
+
+An ordered list. Each entry has `files` (glob patterns, same syntax as `ignorePatterns`) and `rules` (same shape as the top-level `rules`). For a given file, the top-level rules are applied first, then every override whose `files` matches, in order — later entries win.
+
+## Merging with the defaults
+
+At load time the linter merges your file over the built-in defaults:
+
+- `rules` — your entries override the default severity for that rule; rules you don't mention keep their default.
+- `ignorePatterns` — your patterns are appended to the default `['dependencies/**']`.
+- `overrides` — used as given (the default is an empty list).
+
+If the file exists but can't be loaded (syntax error, wrong module format), the linter prints a warning and continues with the defaults.
+
+## Module format
+
+`.eventcatalogrc.js` is loaded with Node's `require`. Use `module.exports` in a CommonJS project. In a project with `"type": "module"`, use `export default`; this is supported on Node.js 20.19 / 22.12 and later, where `require` can load ES modules. `--init` picks the right form automatically.
+
+## `eventcatalog.config.js`
+
+The linter also reads your catalog's `eventcatalog.config.js`, but only for `dependencies`, so that references to resources documented in other catalogs resolve. See [Reference external catalogs](../how-to/reference-external-catalogs). Nothing else in that file affects linting.
+
+## Full example
+
+```js title=".eventcatalogrc.js"
+module.exports = {
+  rules: {
+    // Findings that mean EventCatalog will fail or silently drop something
+    'schema/unknown-field': ['error', { allow: ['legacy*'] }],
+    'refs/resource-exists': 'error',
+    'refs/file-exists': ['error', { publicDir: 'static' }],
+    'structure/unrecognised-file': 'error',
+
+    // Documentation quality
+    'best-practices/description-required': 'warn',
+    'best-practices/schema-required': 'warn',
+    'refs/orphan-messages': 'warn',
+  },
+
+  ignorePatterns: ['drafts/**'],
+
+  overrides: [
+    {
+      files: ['domains/Legacy/**'],
+      rules: {
+        'best-practices/owner-required': 'warn',
+        'best-practices/summary-required': 'off',
+      },
+    },
+    {
+      files: ['**/containers/**'],
+      rules: {
+        'best-practices/description-required': 'off',
+      },
+    },
+  ],
+};
+```

package/dist/docs/development/developer-tools/eventcatalog-linter/reference/03-rules.md

@@ -0,0 +1,287 @@
+---
+sidebar_position: 3
+sidebar_label: Rules
+title: Linter rules reference
+description: Every rule the EventCatalog Linter can report — what it checks, its default severity, its options, an example message and how to fix it.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Rules are grouped into five categories. Each rule can be set to `'error'`, `'warn'` or `'off'` in [`.eventcatalogrc.js`](./configuration); rules marked **options** also accept `[severity, { ... }]`.
+
+| Rule | Default | Options |
+|------|---------|---------|
+| [`schema/required-fields`](#schemarequired-fields) | error | |
+| [`schema/valid-type`](#schemavalid-type) | error | |
+| [`schema/valid-semver`](#schemavalid-semver) | error | |
+| [`schema/valid-email`](#schemavalid-email) | error | |
+| [`schema/validation-error`](#schemavalidation-error) | error | |
+| [`schema/unknown-field`](#schemaunknown-field) | error | `allow`, `suggestions` |
+| [`schema/unknown-nested-field`](#schemaunknown-nested-field) | warn | `allow`, `suggestions` |
+| [`refs/owner-exists`](#refsowner-exists) | error | |
+| [`refs/resource-exists`](#refsresource-exists) | error | |
+| [`refs/valid-version-range`](#refsvalid-version-range) | error | |
+| [`refs/channel-exists`](#refschannel-exists) | error | |
+| [`refs/container-exists`](#refscontainer-exists) | error | |
+| [`refs/file-exists`](#refsfile-exists) | error | `icons`, `publicDir` |
+| [`refs/orphan-messages`](#refsorphan-messages) | warn | |
+| [`best-practices/summary-required`](#best-practicessummary-required) | error | |
+| [`best-practices/owner-required`](#best-practicesowner-required) | error | |
+| [`best-practices/description-required`](#best-practicesdescription-required) | warn | |
+| [`best-practices/schema-required`](#best-practicesschema-required) | warn | |
+| [`versions/no-deprecated-references`](#versionsno-deprecated-references) | warn | |
+| [`structure/duplicate-resource-ids`](#structureduplicate-resource-ids) | error | |
+| [`structure/unrecognised-file`](#structureunrecognised-file) | warn | |
+
+YAML that cannot be parsed at all is reported as `(@eventcatalog/parse-error)`. It is always an error and cannot be configured.
+
+## Schema validation
+
+These rules validate frontmatter against the same schemas EventCatalog uses.
+
+### `schema/required-fields`
+
+A required field is missing from the frontmatter. Which fields are required depends on the resource type; `id`, `name` and `version` are required almost everywhere.
+
+```
+2:1 ✖ error name: Required [name] (schema/required-fields)
+```
+
+**Fix:** add the field.
+
+### `schema/valid-type`
+
+A field has the wrong type — a string where a list is expected, a missing required field reported as `undefined`, and so on.
+
+```
+2:1 ✖ error version: Expected string, but received undefined [version] (schema/valid-type)
+7:9 ✖ error owners: Expected array, but received string [owners] (schema/valid-type)
+```
+
+**Fix:** correct the value's shape. Lists in YAML are written with `- ` items or `[a, b]`.
+
+### `schema/valid-semver`
+
+A `version` (or a version inside a reference) isn't a format EventCatalog understands.
+
+```
+4:10 ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+```
+
+**Fix:** use semver (`1.2.3`, `1.0.0-beta`), a number-like version (`1`, `1.2`, `v1`, `V2`), `latest`, or a range (`^1.0.0`, `1.x`). See the [versions reference](./versions).
+
+### `schema/valid-email`
+
+An `email` field on a user or team isn't a valid email address.
+
+**Fix:** correct the address.
+
+### `schema/validation-error`
+
+A schema problem that doesn't fit the categories above. The message carries the underlying detail.
+
+### `schema/unknown-field`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A top-level frontmatter key isn't part of the resource's schema. EventCatalog rejects unknown top-level keys at build time unless they start with `x-`, so this rule catches typos and stray custom fields before the build does. The message suggests the closest known key, or tells you when the key belongs to a different resource type.
+
+```
+6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
+8:1 ✖ error Unknown property "costCenter". Custom properties must start with "x-". [costCenter] (schema/unknown-field)
+5:1 ✖ error Unknown property "sends". "sends" is valid on service, agent, domain resources, but not on event resources. [sends] (schema/unknown-field)
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allow` | `string[]` | `[]` | Keys, or `prefix*` patterns, to accept. Matched against the key name and the full path |
+| `suggestions` | `boolean` | `true` | Include "Did you mean" and other-resource-type hints |
+
+```js
+'schema/unknown-field': ['error', { allow: ['costCenter', 'legacy*'], suggestions: true }]
+```
+
+Keys starting with `x-` are always allowed, as are the `catalog`, `versions` and `latestVersion` fields the SDK writes into generated content.
+
+**Fix:** rename the key, or prefix it with `x-`. See [Allow custom frontmatter](../how-to/use-custom-frontmatter).
+
+### `schema/unknown-nested-field`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+The same check for keys inside nested objects and arrays (`sends[0].too`, `detailsPanel.ownerz`). EventCatalog silently ignores these rather than failing, which is why the default is `warn` — but a typo here usually means a relationship or setting is being dropped. Options are the same as `schema/unknown-field`, and an `allow` list set on either rule applies to both.
+
+```
+12:9 ⚠ warning Unknown property "sends[0].too". Did you mean "to"? [sends[0].too] (schema/unknown-nested-field)
+```
+
+Arbitrary keys are permitted where the schema allows them — flow step `custom.properties`, channel `parameters`, and any `producers`/`consumers` object.
+
+## Reference validation
+
+These rules check that everything your frontmatter points at actually exists. References can be plain ids (`- order-service`) or objects (`- id: order-service`, optionally with `version`). Version matching follows the [versions reference](./versions).
+
+### `refs/owner-exists`
+
+An entry in `owners` (or an ADR's `decisionMakers`) doesn't match any user or team.
+
+```
+6:5 ✖ error Referenced user/team "platfrom-team" does not exist. Did you mean "platform-team"? [owners[0]] (refs/owner-exists)
+```
+
+**Fix:** correct the id, or add the user (`users/<id>.mdx`) or team (`teams/<id>.mdx`).
+
+### `refs/resource-exists`
+
+A referenced resource id doesn't exist among the resource types the field accepts — `sends`/`receives` (events, commands, queries), `services`, `domains`, `entities`, `flows`, flow steps, ADR `appliesTo`, data product `inputs`/`outputs`, and so on. The message adds a "did you mean" suggestion for near-miss ids, or points out when the id exists as a different resource type.
+
+```
+9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
+9:5 ✖ error Referenced flow "PlaceOrder" does not exist. "PlaceOrder" exists as a command, not a flow. [appliesTo[0]] (refs/resource-exists)
+```
+
+This rule fires whether or not the reference has a version — if the id itself is unknown, the version is irrelevant.
+
+**Fix:** correct the id, create the resource, or declare it as an external [dependency](../how-to/reference-external-catalogs).
+
+### `refs/valid-version-range`
+
+The referenced resource exists, but no version of it satisfies the reference. The message lists the versions that do exist, newest first. It also fires when the version reference isn't a version, range or `latest` at all.
+
+```
+9:14 ✖ error Referenced event "OrderCreated" does not have a version matching "3.0.0". Available versions: 2.0.0, 1.0.0 [sends[0]] (refs/valid-version-range)
+9:14 ✖ error Referenced event "OrderCreated" has an invalid version reference "two". Use a version (1.0.0, v1), a range (^1.0.0, 1.x) or "latest". Available versions: 1.0.0 [sends[0]] (refs/valid-version-range)
+```
+
+**Fix:** reference an existing version or a range that matches one, or add the version under `versioned/`.
+
+### `refs/channel-exists`
+
+A channel referenced from `sends[].to`, `receives[].from`, a message's `channels`, or a channel's `routes`/`channels` doesn't exist (or doesn't exist at that version).
+
+```
+11:9 ✖ error Referenced channel "orders-topic" does not exist. Did you mean "orders"? [sends[0].to[0]] (refs/channel-exists)
+```
+
+### `refs/container-exists`
+
+A container referenced from `writesTo`, `readsFrom`, a system's `containers`, or a container-typed flow step doesn't exist. `dataStore` is accepted as a legacy alias for `container`.
+
+```
+13:5 ✖ error Referenced container "orders-db" does not have a version matching "9.0.0". Available versions: 1.0.0 [writesTo[0]] (refs/container-exists)
+```
+
+### `refs/file-exists`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A file referenced from frontmatter doesn't exist. The linter resolves each path the way EventCatalog does:
+
+| Field | Resolved against |
+|-------|------------------|
+| `schemaPath` | the resource's own folder |
+| `schemas[].file`, `schemas[].path` | the resource's own folder |
+| `schemas[].ref` | `file://<relative>` against the resource folder; `file:///<absolute>` as given. Other refs (schema registries) are skipped |
+| `specifications.openapiPath` / `asyncapiPath` / `graphqlPath`, `specifications[].path` | the resource's own folder; `http(s)://` values are skipped |
+| data product `outputs[].contract.path` | the resource's own folder |
+| `styles.icon` starting with `/` | the catalog's `public/` folder; icon names and URLs are skipped |
+
+Because paths resolve against the resource's own folder, a versioned copy under `versioned/1.0.0/` must have its own schema file next to it.
+
+```
+7:13 ✖ error Referenced schema file "schema.json" does not exist (looked for "events/OrderCreated/schema.json") [schemaPath] (refs/file-exists)
+15:9 ✖ error Referenced icon "/icons/go.svg" does not exist (looked for "public/icons/go.svg") [styles.icon] (refs/file-exists)
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `icons` | `boolean` | `true` | Check `styles.icon` paths |
+| `publicDir` | `string` | `'public'` | Folder, relative to the catalog root, that `/`-prefixed icon paths are served from |
+
+```js
+'refs/file-exists': ['error', { icons: false, publicDir: 'static' }]
+```
+
+### `refs/orphan-messages`
+
+An event, command or query that nothing produces or consumes: no service, agent or domain lists it in `sends`/`receives`, and the message itself has no `producers`/`consumers`. Messages declared as external dependencies are never orphans.
+
+```
+2:5 ⚠ warning event "OrderCreated" has no producer and no consumer [id] (refs/orphan-messages)
+```
+
+**Fix:** connect the message to a service, or turn the rule off for intentionally standalone messages.
+
+## Best practices
+
+Documentation-quality checks. They don't affect whether EventCatalog builds, so tune them to your team's standards.
+
+### `best-practices/summary-required`
+
+The resource has no `summary`, or it's blank. Users are exempt (the user schema has no summary field).
+
+```
+2:1 ✖ error Summary is required for better documentation [summary] (best-practices/summary-required)
+```
+
+### `best-practices/owner-required`
+
+The resource has no `owners`, or the list is empty. Users and teams are exempt.
+
+```
+2:1 ✖ error At least one owner is required [owners] (best-practices/owner-required)
+```
+
+### `best-practices/description-required`
+
+The file has no markdown body after the frontmatter.
+
+```
+14:1 ⚠ warning Resource should have a markdown description (body content) beyond just frontmatter [description] (best-practices/description-required)
+```
+
+### `best-practices/schema-required`
+
+An event, command or query has no `schemaPath`.
+
+```
+2:1 ⚠ warning event should have a schemaPath defined for consumers to understand the contract [schemaPath] (best-practices/schema-required)
+```
+
+## Versioning
+
+### `versions/no-deprecated-references`
+
+A reference points at a resource marked `deprecated`. A reference without a version (or `latest`) is flagged if any version of the target is deprecated; a versioned reference is flagged only if that version is. Owner and team-member references are not checked.
+
+```
+9:5 ⚠ warning Referenced event "OrderCreated" (version: 1.0.0) is deprecated [sends[0]] (versions/no-deprecated-references)
+```
+
+## Catalog structure
+
+### `structure/duplicate-resource-ids`
+
+Two files declare the same resource type, `id` and `version`.
+
+```
+2:5 ✖ error Duplicate event "OrderCreated" (version: 1.0.0) — also defined in domains/Orders/events/OrderCreated/index.mdx [id] (structure/duplicate-resource-ids)
+```
+
+### `structure/unrecognised-file`
+
+<AddedIn version="1.1.17" pkg="@eventcatalog/linter" url="https://github.com/event-catalog/eventcatalog" />
+
+A `.md`/`.mdx` file lives under a resource folder but matches none of the locations EventCatalog loads resources from, so it will be silently ignored. The message suggests where the file probably belongs. Markdown that EventCatalog loads through other means — `docs/` folders, `pages/`, `changelog.md`, `ubiquitous-language.md` — and build artifacts are not reported. Files matched by `ignorePatterns` are skipped.
+
+```
+1:1 ⚠ warning File "events/OrderCreated.mdx" is not recognised as an EventCatalog resource and will be ignored. Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+1:1 ⚠ warning File "event/OrderCreated/index.mdx" is not recognised … Did you mean "events/OrderCreated/index.mdx"? (structure/unrecognised-file)
+1:1 ⚠ warning File "users/john/index.mdx" is not recognised … users are flat files. Did you mean "users/john.mdx"? (structure/unrecognised-file)
+```
+
+Recognised locations are listed in [Supported resources](./supported-resources). Because a misplaced file means the catalog is missing content, consider promoting this rule to `'error'`.